home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 October: Mac OS SDK / Dev.CD Oct 96 SDK / Dev.CD Oct 96 SDK1.toast / Development Kits (Disc 1) / Apple Remote Access API / Documentation / Add-on Security API / Add-on Security API
Encoding:
Text File  |  1994-09-15  |  231.9 KB  |  384 lines  |  [ONLN/HLX2]
  2. Apple Remote Access
  3. Add-on Security Interface
  4. Author:  Farzad Sarabi
  5. Version 1.0
  6. November 4, 1993
  7. Copyright © 1992, 1993 Apple Computer, Inc.
  8.  
  9.  
  10. Table of Contents
  11. Introduction    1
  12. Overview    2
  13. Security Module Structure    5
  14. Module Information Resource ('sinf' ID 200)    6
  15. Code Resource Structure    8
  16. User Configuration (UCNF Resource ID 200)    11
  17. Client-side Protocol (CLPR Resource ID 200)    12
  18. Server-side Protocol (SRPR Resource ID 200)    13
  19. Connection Configuration (CCNF Resource ID 200)    14
  20. Client Side Line-level (CLLN Resource ID 200)    15
  21. Actions    16
  22. kSecurityStartup    16
  23. kSecurityShutdown    16
  24. kSecurityBegin    16
  25. kSecurityEnd    16
  26. kSecurityDataAvailable    16
  27. kSecurityAbort    16
  28. kSecurityTickleAction    17
  29. ARA Service Routines    18
  30. ARARead    19
  31. ARAWrite    21
  32. ARALogMessage    22
  33. ARACallBackAt    23
  34. ARAAllowUser    24
  35. ARADontAllowUser    25
  36. ARAReadSecurityData    26
  37. ARAReadLockSecurityData    27
  38. ARAWriteSecurityData    28
  39. ARAUnlockSecurityData    29
  40. ARAGetUserInfo    30
  41. ARATickleMe    31
  42. ARACompleteOperation    32
  43. Appendix A:  Security Interface Header File    33
  44. Appendix B:  Security Module Shell    41
  45. Appendix C:  Miscellaneous    48
  46. Runtime Environment    48
  47. Building  an Add-on Security Module    48
  48. ARA Security Interface Disk    49
  49.  
  50. Introduction
  51. This document describes the add-on security interface used in Apple Remote Access (ARA).  This document is written for a security module writer, and explains the ARA interface as seen from an add-on security module.
  52. Add-on security modules (security modules) contain code resources that allow additional methods of authenticating users.  ARA uses passwords and a call-back mechanism as its default security.  If you have a system for identifying a user, you can develop a security module to integrate your authentication methods into ARA.
  53. We have defined two types of security devices.  Devices that sit in front of or behind a modem and physically prevent a connection prior to user authentication are called line-level security devices.  Systems that perform their authentication after the ARA server and its client have established a connection are classified as protocol-level security devices.  You can develop security modules for each type of device.
  54. The next section gives a brief overview of add-on security modules.
  55. The Security Module Structure section describes a module and its structure in more detail.
  56. The Code Resources section describes the different kinds of code resources that can exist in a security module.
  57. The Actions section describes the actions ARA sends to code resources to request services.
  58. The ARA Service Routines section describes the services that ARA provides to security modules.
  59. Appendix A is the header file for gaining access to ARA Service Routines.
  60. Appendix B is an empty shell for building a code resource.
  61. Appendix C contains miscellaneous information about security module's such as a modules runtime environment, how you can build a module, and the enclosed developer disk contents.
  62. Overview
  63. A security module is a Macintosh file type 'CLMP'.  The creator is vendor specific.  You can request a creator for your security module from Apple Developer Technical Support (DTS).
  64. Internally a security module contains a number of special resources.  Every module must contain an information resource that describes your modules capabilities.  Additionally your module may contain a number of code resources.  These code resources are executed to perform various functions (e.g. authentication, configuration) for your security module.  ARA then can use your module to authenticate a user's identity beyond the password mechanism that it contains.  ARA security modules that are placed in the Extensions folder.
  65. The following diagram illustrates the contents of a security module:
  66. The information resource is described in the module Information Resource section.
  67. Each of the code resources provides an entry point.  This is a routine which will be called when ARA needs to execute a code resource.  The entry point routine and the operations it must support are described in the Code Resource Structure section.
  68. When a code resource is loaded, it will be able to access ARA to request certain services.  For example it can have data sent to the remote machine.  These services are provided as routines that can be called from a security module.  They are described in the ARA Service Routines section.
  69. The following diagram is a high level view of a loaded code resource:
  70. Security Module Structure
  71. A security module is built by creating a Macintosh file that has a 'CLMP' type.  This is used by ARA to identify the file as a security module.  The module has to be placed in the Extensions folder for ARA to find it.  You can do this by dragging it on top of your system folder after installing ARA.  The module's creator is defined by you.  You must request a creator from Developer Technical Support (DTS).
  72. Additionally the file must contain at least a 'sinf' resource, and a number of code resources for performing various operations.  The 'sinf' resource and the code resources are described below.
  73. Currently there are five types of code resources that ARA supports.  They are described in sub-sections below. 
  74. Code resources must have the appropriate type, and their resource ID should be 200.
  75. Module Information Resource ('sinf' ID 200)
  76. Your module must have a 'sinf' resource with a resource ID of 200.  The 'sinf' resource describes what the module's capabilities are.
  77. In your resource definition file, you should create a 'sinf' resource, and fill in the appropriate fields.  The template for the resource is defined in a file named "SecurityTypes.r".  This file is found on the developer disk.  The following is the template for a 'sinf' resource:
  78. type 'sinf'    {                    /* security information resource */
  79.         unsigned    longint;        /* fflags contains info about module */
  80.         literal        longint;        /* fsignature identifies module */
  81.         unsigned    longint;        /* fversion */
  82.         unsigned     longint;        /* fmin_version */
  83.         unsigned    longint;        /* fmax_version */
  84.         unsigned    longint;        /* fserver_data */
  85.         unsigned    longint;        /* fclient_data */
  86.         pstring[ 31 ];                /* module name */
  87. };
  88. The first longint is a set of flags that define what the capabilities of the module are.  The values for the flags are defined in "SecurityResInfo.h", found on the developer disk.  The values should be a combination of the following using the "OR" operator:
  89. kSecurityHasLineLevel    Use this flag if your module is to be used for line-level authentication of a user.  This flag causes the module to be displayed on the client side.  It let's the user select this module for a connection document, used to connect to a port with a physical security device.    
  90. kSecurityHasProtocolLevel
  91.     This flag indicates the module provides protocol level authentication.  It can be used in combination with the kSecurityHasServerSide and kSecurityHasClientSide flags to indicate if the module supports the client side, server side, or both.    
  92. kSecurityHasServerSide
  93.     This flag is set for a module that provides the code resources needed for the server side.  Any module that has code to be executed on the server should set this flag, including user configuration.    
  94. kSecurityHasClientSide
  95.     This flag is set for a module that provides code resources needed for the client side.  Any module that has code to be executed on the client should set this flag.    
  96. kSecurityHasUserConfig
  97.     This flag is used for a protocol-level module that has a code resource for configuring users on the server.  Has 'UCNF' resource.    
  98. kSecurityHasConnectionConfig
  99.     This flag is used for a line-level module that has a code resource for security configuration on the client side.  Has a 'CCNF' resource.    
  100. kSecurityHasUserDialog    Don't use this flag.    
  101. kSecurityHasConnectionDialog     Don't use this flag.    
  102.  
  103. The second longint is the signature of the module.  This value uniquely identifies your security module.  You should reserve a value through Apple Developer Technical Support (DTS).  This value should be the same as your file's creator, but it can be different.  When they are different, ARA uses the value defined in the 'sinf' resource.  For protocol-level modules this signature is used to associate a client module with the server module.
  104. The next three longints are version numbers and are only used for protocol level modules.  The first field is "fversion" and defines the module's version.  The field after "fversion" are "fmin_version", and "fmax_version".  For protocol-level authentication, they are used for checking the client module's compatibility with the server's.  The client's "fversion" must be a number between the server module's "fmin_version" and "fmax_version". 
  105. The next two longints, "fserver_data" and "fclient_data", are not used, and should be set to zero.
  106. The last field is a Pascal string that is your module's name.  This name is used in dialog boxes and anywhere your modul'es name is displayed.
  107. Code Resource Structure
  108. The following sub-sections describe the structure of code resources.
  109. MySecurityProcEntry
  110. Every code resource must provide a routine named "MySecurityProcEntry".  This is the entry point to the code resource.  ARA calls it through the Security Interface.  It should be defined as follows:
  111. pascal long        MySecurityProcEntry( SecurityActions        Action,
  112.                                      SecurityReference        MyReference,
  113.                                      long                    LongParam )
  114. ARA sends actions to your code resources to request it to perform a service.  You should process the actions and return control to ARA as quickly as possible.  Actions are defined in the file SecurityPublic.h.  The "Actions" section describes actions in detail.  The following is a list of the actions:
  115. kSecurityStartup
  116. kSecurityShutdown
  117. kSecurityBegin
  118. kSecurityEnd
  119. kSecurityDataAvailable,
  120. kSecurityAbort
  121. kSecurityTickleAction
  122. MyReference is a unique value that defines an instance of the code resource.  It is used when you call any of the ARA Service Routines.  It uniquely identifies your thread.
  123. LongParam is used to pass additional information for an action.  Currently it is only used with kSecurityTickleAction.
  124. Your entry routine should process the action as soon as possible.  It should not stay go into any loops.  It can post asynchronous calls to ARA and other Toolbox routines, but it should return control back to ARA quickly.  YOU MUST RETURN CONTROL BACK TO ARA AS SOON AS POSSIBLE.
  125. Your routine's return value is a result code ARA examines for possible errors in "MySecurityProcEntry".  The possible result codes are "SecurityErrors" defined in "SecurityPublic.h".  Return "kSecurityNoErr" if  your routine is successful.
  126. SecurityInterface.o
  127. "SecurityInterface.o" is the glue file that provides the ARA Service Routines.  It must be linked with each code resource.  When linking a code resource, you must have "SecurityInterface.o" as the first file in the linker's object file list.  The MPW linker does not shuffle code.  The entry point to "SecurityInterface.o" must become the entry point to your code resource.
  128. MPW linker uses the -m option to perform code-flow analysis and remove any dead code.  To keep your executable code from being stripped, you must provide the following option in the linker command line:
  129. -m SECURITYINTERFACEENTRYPROC
  130. Completion Routine
  131. Most of the ARA Service Routines are asynchronous.  After an asynch ARA routine finishes, it informs you code resource by calling a completion routine.  Your completion routine should have the following declaration:
  132. pascal void        MyCompletionProc( SecurityReference        MyReference,
  133.                                   int                    ResultCode,
  134.                                   void                    * DataPtr,
  135.                                   int                    DataSize,
  136.                                   long                    CompletionParam )
  137. You pass a pointer to your completion routine as one of the parameters to asynchronous ARA Service Routines.
  138. MyReference should is the same value passed to "MySecurityProcEntry".  It identifies your instance.
  139. ResultCode is the result of the asynchronous ARA Service you had requested.  It will be non zero if the operation failed.  It will contain one of the values in ARAErr defined in SecurityPublic.h.  You should check its value at the start of your completion routine before you do any other processing.  If a read or write times out, the ResultCode will be ARATimeout.
  140. DataPtr is the pointer you passed to the asynch ARA Service Routine.  E.g. this will point to the data read by ARARead.
  141. DataSize will be the actual size of processed data.  E.g. the number of bytes read by ARARead.
  142. CompletionParam is an additional long you provide.  Its value will be the same value you passed to the asynch ARA Service Routine.  You can use it as a state indicator.  E.g. you can define an enumeration containing the set of all your states.  When you call an asynch ARA routine, pass the state you want to be in when the call is done.  E.g. pass "kFinished1stRead" to ARARead.  When your completion routine gets called with CompletionParam equal to "kFinished1stRead", the ARARead has finished and you can go to the next state.  See the sample module on the developer disk for an example of this.
  143. You should not call any Memory Manager routines, or any routines that result in a Memory Manager call from a completion routine.  If you need to call these types of routines, call ARATickleMe and handle it in the kSecurityTickleAction.
  144. Runtime Environment (A5 World)
  145. An A5 World is setup for your code resource by ARA.  You don't need to be concerned with initializing or setting up the A5 world in the code resource.  ARA sets up the A5 world prior to executing any of the code resource (entry routine, and completion routines).  Since the code resource has an A5 world, it you can have static (global) data and use the data the same way as an application.
  146. During the execution of your code resource, the resource fork of the security module is open, and it is put on top of the resource forks stack.  The file is opened in read only mode, so you should not attempt to write any data to the module's resource fork.  A better way of storing data is to store it in a separate preference file, which will not be deleted when you update a user's security module.
  147. You can make calls to Mac Toolbox routines.  Whenever possible you should call asynchronous routines, so you can return control to ARA.  Furthermore, you should not go into any loops or call SystemTask as a way of returning control to ARA.
  148. ARA Service Routines
  149. ARA provides a number of services accessible through ARA Service Routines.  The header file "SecurityInterface.h" has the declarations for these routines.   To use them you must link with "SecurityInterface.o".
  150. The ARA Service Routines are described in detail in a later section.
  151. User Configuration (UCNF Resource ID 200)
  152. This code resource is executed when a user window is open on the ARA server admin, and the security module's configuration button is selected.  It is used for configuring protocol-level security information on a per-user basis.  The code resource should display a modal dialog box and get any needed information.  It can store 150 bytes of data for each user (see ARAWriteSecurityData, and ARAReadSecurityData).
  153. On kSecurityBegin you should start your processing, e.g. request to read the existing security data (ARAReadLockSecurityData), or to get the user's name (ARAGetUserInfo).  When you've obtained this information, you can call ARATickleMe to put up the modal dialog box (it must be a modal dialog box).  You must display the user's name at the top of this dialog box.  The user can then input/modify the information and either save or cancel.  If the user selects to save the data, you must write it out by calling ARAWriteSecurityData.  This information will then be available to the server-side protocol-level authentication module.
  154. The following ARA Service Routines can be used by a UCNF code resource:
  155. ARALogMessage
  156. ARAReadSecurityData
  157. ARAReadLockSecurityData
  158. ARAUnlockSecurityData
  159. ARAWriteSecurityData
  160. ARAGetUserInfo
  161. ARATickleMe
  162. ARACompleteOperation
  163. Client-side Protocol (CLPR Resource ID 200)
  164. This code resource is executed on the ARA client for protocol-level authentication.  The corresponding server-side protocol-level module is also executed on the server, and the two module's can communicate with each other.
  165. The client module's state should be driven by the server, and when the authentication has been completed, both sides should call ARAAllowUser/ARADontAllowUser, so ARA can progress to the next state.
  166. A CLPR module can pass a maximum of 500 bytes of data to ARAWrite/ARARead.  The ARAWrite and ARARead will communicate with the server-side protocol (i.e. ARARead on the client side will read data written by the server module).
  167. On kSecurityBegin you should start your state machine, getting information from the user and sending it to the server module.  The server module should inform the client module when the user is authenticated or rejected, at which time it should call ARAAllowUser, or ARADontAllowUser.
  168. The following ARA Service Routines can be used by a CLPR code resource:
  169. ARARead
  170. ARAWrite
  171. ARALogMessage
  172. ARAAllowUser
  173. ARADontAllowUser
  174. ARATickleMe
  175. ARACompleteOperation
  176. Server-side Protocol (SRPR Resource ID 200)
  177. This code resource is executed on the server to authenticate a user after the ARA protocol has been established.  It can communicated with the corresponding client authentication module.  ARA loads the client module automatically.
  178. This code resource should get the user information from the client module and determine if the user should be allowed in.  Once a user has been authenticated or rejected, this code resource should inform the client side, and then call ARAAllowUser/ARADontAllowUser.  The client code resource should also call ARAAllowUser/ARADontAllowUser.
  179. A SRPR code resource can write and read a maximum of 500 bytes of data using ARAWrite or ARARead.  The data is exchanged with client module.
  180. This code resource can use ARAReadLockSecurityData, ARAReadSecurityData, ARAWriteSecurityData, and ARAUnlockSecurityData to access and modify the 150 bytes of security data associated with each user.  Each security module can have 150 bytes of data for each user.
  181. The following ARA Service Routines can be used by a SRPR code resource:
  182. ARARead
  183. ARAWrite
  184. ARALogMessage
  185. ARACallBackAt
  186. ARAAllowUser
  187. ARADontAllowUser
  188. ARAReadSecurityData
  189. ARAReadLockSecurityData
  190. ARAUnlockSecurityData
  191. ARAWriteSecurityData
  192. ARAGetUserInfo
  193. ARAGetMySessionRef
  194. ARATickleMe
  195. ARACompleteOperation
  196. Connection Configuration (CCNF Resource ID 200)
  197. A Connection Configuration code resource is executed on the client side when the user selects "Configuration" button on the client in a connection document's security option.  It can store 150 bytes of data in a connection document for a line-level security device.
  198. It should display a modal dialog and get any information relevant to connections with line-level security.  You can use ARAReadLockSecurityData, ARAReadSecurityData, ARAWriteSecurityData, and ARAUnlockSecurityData to access and modify the security data.
  199. On kSecurityBegin you should get the existing security data.  Once you have obtained the data, you should display a dialog box, and allow the user to modify it.  When the user is done, you can write the security data if it was modified, using ARAWriteSecurityData.
  200. The following ARA Service Routines can be used by a CCNF code resource:
  201. ARAReadSecurityData
  202. ARAReadLockSecurityData
  203. ARAUnlockSecurityData
  204. ARAWriteSecurityData
  205. ARATickleMe
  206. ARACompleteOperation
  207. Client Side Line-level (CLLN Resource ID 200)
  208. A client-side line-level code resource is executed after a physical connection has been established, using a connection document configured with security.  It should communicate with the line-level device, prompting the user for any information the device requires.
  209. A CLLN code resource can use the ARARead and ARAWrite to communicate with the line-level device on the server.  The data being read or written is sent over the physical line without any packetization.  Your code resource gets control of the line after a connection is established, but before your authentication device allows connection to the ARA server.
  210. On kSecurityBegin you should start the communication process with the server line-level device.  You can display a dialog box to obtain information from the user.  Once the physical device has authenticated or rejected the user the code resource should call ARAAllowUser or ARADontAllowUser to let ARA transition to the next state.
  211. You can use ARAReadSecurityData to access the 150 bytes of data stored in the connection document.  You can not modify this information during authentication.  The security data is stored in an alias to a remote server as well as the original connection document, so you can get the data even if the connection is initiated from an alias to a remote server.
  212. A CLLN code resource can use the following ARA Service Routines:
  213. ARARead
  214. ARAWrite
  215. ARAAllowUser
  216. ARADontAllowUser
  217. ARAReadSecurityData
  218. ARATickleMe
  219. ARACompleteOperation
  220. Actions
  221. Actions are one of the parameters passed to your code resource's entry routine.  ARA sends them to request a service from your code resource. 
  222. All actions are sent during main thread time, so you can allocate memory and make calls to Mac Toolbox routines.  The code resource's A5 world is setup prior to calling your routine.  The resource fork of your module is open and on top of the resources stack.
  223. You should process actions as quickly as possible.  You should not go into loops and use SystemTask calls as a way of returning control back to ARA.
  224. kSecurityStartup
  225. kSecurityStartup is sent immediately after your code resource is loaded.  You can allocate any needed memory during the processing of this action, but you should not make any calls to any of the ARA Service Routines.  Once processed, you should return kSecurityNoErr.  Generally you should use kSecurityBegin to start any processing.
  226. kSecurityShutdown
  227. kSecurityShutdown is the last action sent prior to unloading your code resource.  The code resource will not be called any more after this action.  You can release any allocated memory.  Make sure you have cleaned everything up before returning.  You can not use any of the ARA Service Routines during kSecurityShutdown.
  228. kSecurityBegin
  229. kSecurityBegin is sent to request your code resource to perform its operation.  E.g. requesting a protocol-level module to authenticate a user.  The code resource should start the operation that it is responsible for.  You can allocate memory and other needed resources.  You can also call ARA Service Routines asynchronously.
  230. kSecurityEnd
  231. kSecurityEnd is sent when the operations that the resource performs are being finished.  You should do your cleanup at this time.  You can not make any calls to ARA Service Routines after or during this action.
  232. kSecurityDataAvailable
  233. kSecurityDataAvailable is not being used in this release.
  234. kSecurityAbort
  235. kSecurityAbort is sent when the operation of your code resource is being aborted.  You should stop any further processing by your code resource (including in your completion routine.  E.g. through the use of a flag).  Your code resource should terminate any outstanding asynch calls to routines other than ARA Service Routines.  Outstanding ARA Service Routines will be aborted by ARA.
  236. kSecurityTickleAction
  237. kSecurityTickleAction is sent to your code resource periodically.  You can also request a kSecurityTickleAction explicitly by calling the ARATicleMe routine.  When you call ARATickleMe you pass an additional parameter which is sent to your "MySecurityProcEntry" as the LongParam.  This additional parameter can be used as a state indicator.  E.g. an asynchronous call has finished, so from your completion routine you call ARATickleMe with the state indicator "DidMyAsynchCall" (this can be a value in an enum).  In processing of kSecurityTickleAction you check the LongParam to see if it matches "DidMyAsynchCall".  If it matches you know you have finished your asynchronous operation and are ready to transition to the next state.  You should also do an ARATickleMe when you need to perform main thread time operations (e.g. allocate memory) .  When kSecurityTickleAction is being sent periodically by ARA LongParam will be 0.  For an example on the use of kSecurityTickleAction and ARATickleMe refer to the Sample module.
  238. ARA Service Routines
  239. ARA Service Routines are a set of functions that code resources have access to.  Using these routines, code resources can request ARA services.  The following is a list of ARA Service Routines:
  240. ARARead
  241. ARAWrite
  242. ARALogMessage
  243. ARACallBackAt
  244. ARAAllowUser
  245. ARADontAllowUser
  246. ARAReadSecurityData
  247. ARAReadLockSecurityData
  248. ARAWriteSecurityData
  249. ARAUnlockSecurityData
  250. ARAGetUserInfo
  251. ARATickleMe
  252. ARACompleteOperation
  253. The following sub-sections describe each of the routines.  
  254. Note
  255. All of the routines expect a MyReference parameter.  This value is passed to "MySecurityProcEntry", and is a unique value representing the instance of the security code resource.
  256. ARARead
  257. Syntax
  258. pascal ARAErr    ARARead( SecurityReference        MyReference,
  259.                          void                    * DataPtr,
  260.                          int                    DataSize,
  261.                          SecurityCompletionProc    CompletionProc,
  262.                          long                    CompletionParam );
  263. Description
  264. This routine is used to issue an asynchronous read call to ARA.  The read will complete either when ARA times out, or the number of bytes requested is read.  This read is used to read data coming from the remote machine.  The protocol-level modules read from each other.  The line-level module reads from a device on the server side.
  265. Parameters
  266. MyReference is the unique identifier passed to the code resource's entry routine.
  267. DataPtr points to a location where the data will be read to.  It must not be released while the asynchronous read has not completed.
  268. DataSize is the maximum number of bytes to be read to DataPtr.  The maximum data size is 500 bytes.
  269. CompletionProc is a function pointer you provide to be called when the read operation has been completed.  If a time-out occurs the CompletionProc is called with a kARATimeout result code.
  270. CompletionParam is additional information you can provide which will be passed to the CompletionProc.
  271. Return Value
  272. Result code.  Non kARANoErr result codes are usually because the call was not queued.
  273. Note
  274. This is an asynchronous call and can be called during interrupt time.  The DataPtr field must not be released until the call has completed.
  275. See Also
  276. ARAWrite
  277. ARAWrite
  278. Syntax
  279. pascal ARAErr    ARAWrite( SecurityReference            MyReference,
  280.                           void                        * DataPtr,
  281.                           int                        DataSize,
  282.                           SecurityCompletionProc    CompletionProc,
  283.                           long                        CompletionParam );
  284. Description
  285. This routine can be used to write data to the remote machine.  For protocol-level authentication the data is transferred over a reliable link, whereas for line-level authentication the data is just transferred over the connection without any packetization.  Protocol-level modules write to each other.  Line-level modules write to a security device on the server side.
  286. Parameters
  287. MyReference is the unique reference passed to the code resource's entry routine.
  288. DataPtr is a pointer to the data to be written out.
  289. DataSize is the number of bytes to be written.  A maximum of 500 bytes can be written.
  290. CompletionProc is a pointer to a completion routine which will be called when the write has been completed.
  291. CompletionParam is additional information you can provide which will be passed to the CompletionProc.
  292. Return Value
  293. Result code.  Errors are usually caused when the write call can not be queued.
  294. Note
  295. This is an asynchronous call and can be called at interrupt time.  The DataPtr field must not be released until the call has been completed.
  296. See Also
  297. ARARead
  298. ARALogMessage
  299. Syntax
  300. extern pascal ARAErr ARALogMessage( SecurityReference    MyReference,
  301.                                     char                * Message,
  302.                                     SecurityCompletionProc CompletionProc,
  303.                                     long                CompletionParam );
  304. Description
  305. You can use this routine to have a message logged to the ARA log file.
  306. Parameters
  307. Message is a Pascal string which will be stored in the log file.
  308. Return Value
  309. Result code.
  310. Note
  311. This is an asynchronous call that can be made during interrupt time.
  312. ARACallBackAt
  313. Syntax
  314. pascal ARAErr ARACallBackAt( SecurityReference        MyReference,
  315.                                char                    * DialString,
  316.                              SecurityCompletionProc    CompletionProc,
  317.                              long                    CompletionParam );
  318. Description
  319. This routine can be used to change the phone number which ARA will call back at.  In order for this routine to work the call-back must be enabled for the given user.  The call-back won't be executed until all other add-on security modules have been executed.
  320. The new number is only used for the current session, and won't change the permanent call-back number.
  321. Parameters
  322. DialString is a Pascal string which contains the phone number to dial.  It must be a valid phone number.
  323. CompletionProc is a routine pointer which will be called when the phone number has been assigned (not when the call-back has been made).
  324. CompletionParam can contain additional information you can supply to be passed on to the CompletionProc.
  325. Return Value
  326. Result code.
  327. Note
  328. This is an asynchronous call that can be made at interrupt time.
  329. The CompletionProc is called when the DialString has been stored by ARA.  Since another security module could override this DialString by another call to this routine, the user may not get called at this DialString.
  330. This routine can only be used by a server-side protocol-level code resource (SRPR)
  331. ARAAllowUser
  332. Syntax
  333. pascal ARAErr  ARAAllowUser( SecurityReference        MyReference,
  334.                              SecurityCompletionProc    CompletionProc,
  335.                              long                    CompletionParam );
  336. Description
  337. This routine is used to let ARA know that the user has been authenticated.  It also informs ARA that the operation has been completed.  ARA will then send the code resource's entry routine a kSecurityEnd action, after which ARA proceeds to the next state.
  338. Parameters
  339. CompletionProc is a completion routine which will be called when ARA has accepted this call.
  340. CompletionParam is additional information you can supply that will be provided to the CompletionProc.
  341. Return Value
  342. Result code.
  343. Note
  344. This is an asynchronous call that can be made during interrupt time.
  345. See Also
  346. ARADontAllowUser, ARACompleteOperation
  347. ARADontAllowUser
  348. Syntax
  349. pascal ARAErr  ARADontAllowUser( SecurityReference        MyReference,
  350.                                  char                    * Message,
  351.                                  SecurityCompletionProc    CompletionProc,
  352.                                  long                    CompletionParam );
  353. Description
  354. You can call this routine when the user has failed authentication.  ARA will send a kSecurityEnd action to the code resources entry routine, after which ARA will tear down the connection.
  355. Parameters
  356. Message is an optional Pascal string which states why the user failed authentication.  You can pass a NIL for the pointer.
  357. CompletionProc is your routine which will be called when ARA has accepted this call.
  358. CompletionParam is a parameter you can supply which is passed to the CompletionProc.
  359. Return Value
  360. Result code.
  361. Note
  362. This is an asynchronous call that can be made during interrupt time.
  363. See Also
  364. ARAAllowUser, ARACompleteOperation
  365. ARAReadSecurityData
  366. Syntax
  367. pascal ARAErr  ARAReadSecurityData( SecurityReference    MyReference,
  368.                                     void                * DataPtr,                                            int                    DataSize,
  369.                             SecurityCompletionProc        CompletionProc,
  370.                                     long                CompletionParam );
  371. Description
  372. This routine is used to read data for the given type of security module which is associated with either a user or a connection.  On the server this data is associated with a given user.  On the client side this data is associated with the connection.  The maximum amount of data that can be stored is 150 bytes.
  373. Parameters
  374. DataPtr points to where the security data is to be read to.
  375. DataSize is the maximum amount of data to read.  It should not be larger than 150.
  376. CompletionProc is a pointer to a routine which will be called when the data has been read.
  377. CompletionParam is additional information you can provide to be passed to the CompletionProc
  378. Return Value
  379. Result code.
  380. Note
  381. On the ARA server this data is associated with a given user and stored in the users and groups database.  On the client side this data is associated with a given connection.
  382. See Also
  383. ARAReadLockSecurityData, ARAWriteSecurityData, ARAUnlockSecurityData
  384. ARAReadLockSecurityData
  385. Syntax
  386. pascal ARAErr  ARAReadLockSecurityData( SecurityReference    MyReference,
  387.                                       void                * DataPtr,                                             int                DataSize,
  388.                             SecurityCompletionProc        CompletionProc,
  389.                                         long                CompletionParam );
  390. Description
  391. This routine is used to read and lock data for the given type of security module which is associated with either a user or a connection.  On the server this data is associated with a given user.  On the client side this data is associated with the connection.  The maximum amount of data that can be read or written is 150 bytes.  You should use the ARAReadLockSecurityData instead of ARAReadSecurityData if you plan to modify or write the security data.  This is crucial on the server, because you can have multiple threads attempting to modify the same data.
  392. Parameters
  393. DataPtr points to where the security data is to be read to.
  394. DataSize is the maximum amount of data to read.  It should not be larger than 150.
  395. CompletionProc is a pointer to a routine which will be called when the data has been read.
  396. CompletionParam is additional information you can provide to be passed to the CompletionProc
  397. Return Value
  398. Result code.
  399. Note
  400. On the ARA server this data is associated with a given user and stored in the users and groups database.  On the client side this data is associated with a given connection.
  401. You must call ARAUnlockSecurityData to remove the lock from the security data.
  402. See Also
  403. ARAReadSecurityData, ARAWriteSecurityData, ARAUnlockSecurityData
  404. ARAWriteSecurityData
  405. Syntax
  406. pascal ARAErr ARAWriteSecurityData( SecurityReference    MyReference,
  407.                                     void                * DataPtr,
  408.                                     int                    DataSize,
  409.                                SecurityCompletionProc    CompletionProc,
  410.                                     long                CompletionParam );
  411. Description
  412. This routine can be used by the security modules (mostly configuration code resources) to store configuration data which is associated with either a user or a connection.  On the server this data is associated with a user.  On the client this data is associated with a connection.
  413. Parameters
  414. DataPtr points to the data to be stored.
  415. DataSize is the number of bytes to store.  It should be less than or equal to 150.
  416. CompletionProc is a pointer to a completion routine that will be called when the data has been written.
  417. CompletionParam is additional information you can provide to be passed to the CompletionProc.
  418. Return Value
  419. Result code.
  420. Note
  421. On the ARA server this data is associated with a given user and stored in the users and groups database.  On the client side this data is associated with a given connection.
  422. A line-level authentication code resource (CLLN) can not modify the security data.
  423. See Also
  424. ARAReadSecurityData, ARAReadLockSecurityData, , ARAUnlockSecurityData
  425. ARAUnlockSecurityData
  426. Syntax
  427. pascal ARAErr ARAUnlockSecurityData( SecurityReference    MyReference,
  428.                                SecurityCompletionProc    CompletionProc,
  429.                                       long                CompletionParam );
  430. Description
  431. This routine removes a lock from security data that has been locked using ARAReadLockSecurityData.
  432. Parameters
  433. CompletionProc is a pointer to a completion routine that will be called when the data has been written.
  434. CompletionParam is additional information you can provide to be passed to the CompletionProc.
  435. Return Value
  436. Result code.
  437. Note
  438. You must call ARAUnlockSecurityData after you have called ARAReadLockSecurityData.
  439. See Also
  440. ARAReadSecurityData, ARAReadLockSecurityData, ARAWriteSecurityData
  441. ARAGetUserInfo
  442. Syntax
  443. pascal ARAErr    ARAGetUserInfo( SecurityReference    MyReference,
  444.                                 void                * DataPtr,
  445.                                 int                    DataSize,
  446.                                 SecurityCompletionProc    CompletionProc,
  447.                                 long                CompletionParam );
  448. Description
  449. This routine is used to get information about the user.  Currently it returns the user's name.  On the server this is the information for the user dialing in, or being configured.
  450. Parameters
  451. DataPtr points to where this information will be stored.
  452. DataSize is the maximum number of bytes to be read.
  453. CompletionProc is a completion routine that will be called when the information has been read.
  454. CompletionParam is additional information you can provide to be passed to the CompletionProc.
  455. Return Value
  456. Result code.
  457. ARATickleMe
  458. Syntax
  459. pascal ARAErr    ARATickleMe( SecurityReference        MyReference,
  460.                              long                    TickleParam );
  461. Description
  462. This routine causes ARA to send a  kSecurityTickleAction to the code resource's entry routine.  For example, you can use this routine from completion routines to have your entry routine invoked.
  463. Parameters
  464. TickleParam is additional information you can provide which will be passed to the entry routine in its LongParam parameter.  When ARA calls the entry routine with a kSecurityTickleAction it passes a 0 for the LongParam parameter.  You can use this as a state indicator.
  465. Return Value
  466. Result code.
  467. Note
  468. This function can be called during interrupt time.  The kSecurityTickleAction is sent to the "MySecurityProcEntry" at SystemTask time.
  469. See Also
  470. kSecurityTickleAction
  471. ARACompleteOperation
  472. Syntax
  473. pascal ARAErr    ARACompleteOperation( SecurityReference     MyReference );
  474. Description
  475. You call this routine when you need to end the operation the code resource is performing.  It causes ARA to send a kSecurityEnd action.  For example the configuration code resource should call this routine when the user has finished inputting information into its dialog box.
  476. Parameters
  477. MyReference is the unique reference passed to the code resource's entry routine.
  478. Return Value
  479. Result code.
  480. See Also
  481. kSecurityBegin, and kSecurityEnd actions
  482. Appendix A:  Security Interface Header File
  483. //234567890123456789012345678901234567890123456789012345678901234567890123456789
  484. //===========================================================================
  485. //    File:    SecurityInterface.h
  486. //
  487. //    This file is the header file which a third party security vendor can
  488. //    use to create an add-on security module.  The add-on security modules
  489. //    can be used to integrate a security device with Apple Remote Access.
  490. //
  491. //    Copyright © 1992, 1993 Apple Computer Inc.
  492. //    All rights reserved
  493. //
  494. //    Author:  Farzad Sarabi
  495. //
  496. //    Modification history:
  497. //
  498. //    9/29/1993    Farzad        Removed declarations for some routines that were
  499. //                            obsolete.
  500. //    2/15/1993    Farzad        The A5 world and a working environment is now
  501. //                            setup for the security modules.  As a result of
  502. //                            this some of the routines in this module are
  503. //                            obsolete.  Among these are ARAGet/SetMyPrivateData,
  504. //                            ARAGetMyResFile.
  505. //    10/6/1992    Farzad        Created
  506. //===========================================================================
  507. #ifndef SECURITY_INTERFACE
  508. #define SECURITY_INTERFACE 1
  509. #ifndef __FILES__
  510. #include    <Files.h>
  511. #endif
  512. #ifndef SECURITY_PUBLIC
  513. #include    "SecurityPublic.h"
  514. #endif
  515. //===========================================================================
  516. //    Macros
  517. //===========================================================================
  518. #define kSecurityInterfaceVersion 0x0100    // 0x0100 will be release 1
  519. #ifdef __cplusplus
  520. extern "C"    {                // in case we are linking into C++ code
  521. #endif
  522. //===========================================================================
  523. //    Types
  524. //===========================================================================
  525. // actions are defined in the SecurityPublic.h file
  526. // ARAErr is defined in SecurityPublic.h
  527. // SecurityEntryProc is defined in SecurityPublic.h
  528. // SecurityCompletionProc is defined in SecurityPublic.h
  529. //===========================================================================
  530. //    Data
  531. //===========================================================================
  532. //===========================================================================
  533. //    Functions
  534. //===========================================================================
  535. // the following are functions you can call to have AppleTalk Remote Access
  536. // perform these services
  537. extern pascal ARAErr    ARARead( SecurityReference        MyReference,
  538.                                  void                    * DataPtr,
  539.                                  int                    DataSize,
  540.                                  SecurityCompletionProc    CompletionProc,
  541.                                  long                    CompletionParam );
  542. //===========================================================================
  543. //    Description:    this routine is used to post an asynchronous read
  544. //                    operation for data coming from the remote machine.
  545. //                    This routine can be used by line-level and protocol-level
  546. //                    authentication modules.  It is not available for 
  547. //                    configuration modules.
  548. //
  549. //    Parameters:        MyReference        this module's unique reference
  550. //                    DataPtr            where to put the read data
  551. //                    DataSize        the maximum number of bytes to read
  552. //                    CompletionProc    this routine will be called when the
  553. //                                    read request has finished
  554. //                    CompletionParam    this is information you can provide to
  555. //                                    be passed to the completion proc
  556. //
  557. //    Return Value:    ARAErr            result code, nonzero indicates an error
  558. //
  559. //    Creation Date:    10/6/1992
  560. //
  561. //    Modifications:
  562. //
  563. //===========================================================================
  564. extern pascal ARAErr    ARAWrite( SecurityReference            MyReference,
  565.                                   void                        * DataPtr,
  566.                                   int                        DataSize,
  567.                                   SecurityCompletionProc    CompletionProc,
  568.                                   long                        CompletionParam );
  569. //===========================================================================
  570. //    Description:    this routine is used to asynchronously write data to
  571. //                    the remote machine.  It can be used by line-level and
  572. //                    protocol-level authentication modules.
  573. //
  574. //    Parameters:        MyReference        your unique reference
  575. //                    DataPtr            the data to be written out
  576. //                    DataSize        the amount of data to write
  577. //                    CompletionProc    this routine is called when the data
  578. //                                    has been written out
  579. //                    CompletionParam    this is extra information you can provide
  580. //                                    to be passed to the CompletionProc
  581. //
  582. //    Return Value:    ARAErr            result code, nonzero indicates an error
  583. //
  584. //    Creation Date:    10/6/1992
  585. //
  586. //    Modifications:
  587. //
  588. //===========================================================================
  589. extern pascal ARAErr ARALogMessage( SecurityReference        MyReference,
  590.                                     char                    * Message,
  591.                                     SecurityCompletionProc    CompletionProc,
  592.                                     long                    CompletionParam );
  593. //===========================================================================
  594. //    Description:    you can use this routine to put a message in AppleTalk
  595. //                    remote accesses log file.
  596. //
  597. //    Parameters:        MyReference        your unique reference
  598. //                    Message            a Pascal string which will be logged to
  599. //                                    in the log file
  600. //                    CompletionProc    this routine will be called when the
  601. //                                    log message has been completed.
  602. //                    CompletionParam    additional information you can supply to
  603. //                                    be passed on to the completion proc
  604. //
  605. //    Return Value:    ARAErr            result code, nonzero indicates an error
  606. //
  607. //    Creation Date:    10/6/1992
  608. //
  609. //    Modifications:
  610. //
  611. //===========================================================================
  612. extern pascal ARAErr ARACallBackAt( SecurityReference        MyReference,
  613.                                     char                    * DialString,
  614.                                     SecurityCompletionProc    CompletionProc,
  615.                                     long                    CompletionParam );
  616. //===========================================================================
  617. //    Description:    this routine can be used during authentication to
  618. //                    cause the server to call the client back at the
  619. //                    specified number.
  620. //
  621. //    Parameters:        MyReference        your unique reference
  622. //                    DialString        this is a pascal string which must
  623. //                                    contain a dial string for the number
  624. //                                    to call the client back at
  625. //                    CompletionProc    this proc will be called when the callback
  626. //                                    has been completed.
  627. //                    CompletionParam    additional information you can provide
  628. //                                    that will be passed to the CompletionProc
  629. //
  630. //    Return Value:    ARAErr            result code, nonzero indicates an error
  631. //
  632. //    Creation Date:    10/6/1992
  633. //
  634. //    Modifications:
  635. //
  636. //===========================================================================
  637. extern pascal ARAErr  ARAAllowUser( SecurityReference        MyReference,
  638.                                     SecurityCompletionProc    CompletionProc,
  639.                                     long                    CompletionParam );
  640. //===========================================================================
  641. //    Description:    the authentication code on the server can call this
  642. //                    routine to indicate the user has passed this module's
  643. //                    security requirements.
  644. //
  645. //    Parameters:        MyReference        your unique reference
  646. //                    CompletionProc    this routine is called when AppleTalk
  647. //                                    Remote Access has finished handling
  648. //                                    your authentication information.
  649. //
  650. //    Return Value:    ARAErr            result code, nonzero indicates an error
  651. //
  652. //    Creation Date:    10/6/1992
  653. //
  654. //    Modifications:
  655. //
  656. //===========================================================================
  657. extern pascal ARAErr  ARADontAllowUser( SecurityReference        MyReference,
  658.                                         char                    * Message,
  659.                                         SecurityCompletionProc    CompletionProc,
  660.                                         long                    CompletionParam );
  661. //===========================================================================
  662. //    Description:    the server security module can call this routine to
  663. //                    prevent a user from being allowed in.
  664. //
  665. //    Parameters:        MyReference        your unique reference
  666. //                    Message            a pascal string stating why the user
  667. //                                    was not allowed access
  668. //                    CompletionProc    this routine will be called when the
  669. //                                    request for not allowing user has bee
  670. //                                    processed
  671. //                    CompletionParam    additional information you can provide
  672. //                                    which will be passed to the completion
  673. //                                    proc
  674. //
  675. //    Return Value:    ARAErr            result code, nonzero indicates an error
  676. //
  677. //    Creation Date:    10/6/1992
  678. //
  679. //    Modifications:
  680. //
  681. //===========================================================================
  682. extern pascal ARAErr  ARAReadSecurityData( SecurityReference    MyReference,
  683.                                            void                    * DataPtr,
  684.                                            int                    DataSize,
  685.                                     SecurityCompletionProc        CompletionProc,
  686.                                            long                    CompletionParam );
  687. //===========================================================================
  688. //    Description:    this routine can be used to read data for this security
  689. //                    module which is associated with either a user (on the
  690. //                    server side), or a connection (on the client side).
  691. //                    This routine doesn't lock the data, so use it only when
  692. //                    you just plan to read the data.
  693. //
  694. //    Parameters:        MyReference        your unique reference
  695. //                    DataPtr            where the data will be read to
  696. //                    DataSize        maximum number of bytes to read
  697. //                    CompletionProc    this routine will be called when the
  698. //                                    read request has completed
  699. //                    CompletionParam    additional information you can provide
  700. //                                    to be passed to the completion proc
  701. //
  702. //    Return Value:    ARAErr            result code, nonzero indicates an error
  703. //
  704. //    Creation Date:    10/6/1992
  705. //
  706. //    Modifications:
  707. //
  708. //===========================================================================
  709. extern pascal ARAErr ARAReadLockSecurityData( SecurityReference    MyReference,
  710.                                               void                * DataPtr,
  711.                                               int                DataSize,
  712.                                         SecurityCompletionProc    CompletionProc,
  713.                                               long                CompletionParam );
  714. //===========================================================================
  715. //    Description:    this routine can be used to read security data and lock
  716. //                    it to be modified.  If you are planning on modifying your
  717. //                    data and then writing it, you must call this routine.
  718. //                    It locks the data until the a ARAUnlockSecurityData call.
  719. //
  720. //    Parameters:        MyReference        your unique reference
  721. //                    DataPtr            where the data will be read
  722. //                    DataSize        the maximum number of bytes to read
  723. //                    CompletionProc    this routine will be called when the
  724. //                                    data is read into your buffer.
  725. //                    CompletionParam    additional information you can provide to
  726. //                                    be passed on to the CompletionProc.
  727. //
  728. //    Return Value:    ARAErr            result code, nonzero indicates an error
  729. //
  730. //    Creation Date:    10/29/1992
  731. //
  732. //    Modifications:
  733. //
  734. //===========================================================================
  735. extern pascal ARAErr    ARAUnlockSecurityData( SecurityReference    MyReference,
  736.                                             SecurityCompletionProc    CompletionProc,
  737.                                                long                    CompletionParam );
  738. //===========================================================================
  739. //    Description:    if you have read the security data with ARAReadLockSecurityData
  740. //                    you must call this routine to unlock the data.  After this
  741. //                    call others can then lock the security data.
  742. //
  743. //    Parameters:        MyReference        your unique reference
  744. //                    CompletionProc    this routine is called when the data is unlocked
  745. //                    CompletionParam    additiona information you can provide to be
  746. //                                    passed to the CompletionProc
  747. //
  748. //    Return Value:    ARAErr            result code, nonzero indicates an error
  749. //
  750. //    Creation Date:    10/29/1992
  751. //
  752. //    Modifications:
  753. //
  754. //===========================================================================
  755. extern pascal ARAErr ARAWriteSecurityData( SecurityReference    MyReference,
  756.                                            void                    * DataPtr,
  757.                                            int                    DataSize,
  758.                                        SecurityCompletionProc CompletionProc,
  759.                                            long                CompletionParam );
  760. //===========================================================================
  761. //    Description:    this routine can be used by the module to write private
  762. //                    data which is either associated with a user (on the server
  763. //                    side), or a connection (on the client side).
  764. //
  765. //    Parameters:        MyReference        your unique reference
  766. //                    DataPtr            the data to be written out
  767. //                    DataSize        the amount of data to write out
  768. //                    CompletionProc    this routine is called when AppleTalk
  769. //                                    Remote Access has completed the write
  770. //                                    operation
  771. //                    CompletionParam    additional information you can provide
  772. //                                    which is passed to the completion proc
  773. //
  774. //    Return Value:    ARAErr            result code, nonzero indicates an error
  775. //
  776. //    Creation Date:    10/6/1992
  777. //
  778. //    Modifications:
  779. //
  780. //===========================================================================
  781. extern pascal ARAErr    ARAGetUserInfo( SecurityReference    MyReference,
  782.                                         void                * DataPtr,
  783.                                         int                    DataSize,
  784.                                     SecurityCompletionProc    CompletionProc,
  785.                                         long                CompletionParam );
  786. //===========================================================================
  787. //    Description:    this routine can be called to get information about the
  788. //                    the user, such as user name etc.  It is an asynchronous
  789. //                    call.
  790. //
  791. //    Parameters:        MyReference        your unique code reference
  792. //                    DataPtr            pointer to where the user's name (Pascal
  793. //                                    string) will be stored
  794. //                    DataSize        maximum number of bytes to read
  795. //                    CompletionProc    this routine will be called when the call
  796. //                                    has completed
  797. //                    CompletionParam    additional information to be passed to
  798. //                                    the CompletionProc
  799. //
  800. //    Return Value:    ARAErr            result code, nonzero indicates an error
  801. //
  802. //    Creation Date:    10/6/1992
  803. //
  804. //    Modifications:
  805. //
  806. //===========================================================================
  807. extern pascal long    ARAGetMySessionRef( SecurityReference    MyReference );
  808. //===========================================================================
  809. //    Description:    You can call this routine to obtain the session reference
  810. //                    for the connection for which your code is loaded.  This
  811. //                    value is unique and stays the same during the connection.
  812. //                    If you have a security module which has both a line-level
  813. //                    and a protocol-level authentication, you can use this
  814. //                    unique reference as a key to communicate between the
  815. //                    code resources.
  816. //
  817. //    Parameters:        MyReference        this is your code's unique reference
  818. //
  819. //    Return Value:    long            the session reference, NULL if there is an
  820. //                                    error
  821. //
  822. //    Creation Date:    10/29/1992
  823. //
  824. //    Modifications:
  825. //
  826. //===========================================================================
  827. extern pascal ARAErr    ARATickleMe( SecurityReference        MyReference,
  828.                                      long                    TickleParam );
  829. //===========================================================================
  830. //    Description:    this routine can be used to have AppleTalk Remote Access
  831. //                    call your entry routine with a kSecurityTickleAction.
  832. //                    You can also provide some additional information which
  833. //                    is passed to the entry routine.
  834. //
  835. //    Parameters:        MyReference        your unique reference
  836. //                    TickleParam        additional information you can provide
  837. //                                    which is passed to the entry proc
  838. //
  839. //    Return Value:    ARAErr            result code, nonzero indicates an error
  840. //
  841. //    Creation Date:    10/6/1992
  842. //
  843. //    Modifications:
  844. //
  845. //===========================================================================
  846. extern pascal ARAErr ARACompleteOperation( SecurityReference     MyReference );
  847. //===========================================================================
  848. //    Description:    this routine can be called to terminate an operation.
  849. //                    It causes ARA to send a kSecurityEnd action.  During
  850. //                    configuration for example the code resource can call
  851. //                    this routine to indicate that configuration has
  852. //                    completed.
  853. //
  854. //    Parameters:        MyReference        your unique reference
  855. //
  856. //    Return Value:    ARAErr            result code, nonzero indicates an error
  857. //
  858. //    Creation Date:    10/6/1992
  859. //
  860. //    Modifications:
  861. //
  862. //===========================================================================
  863. #ifdef __cplusplus
  864. }
  865. #endif
  866. #endif // SECURITY_INTERFACE
  867. Appendix B:  Security Module Shell
  868. //234567890123456789012345678901234567890123456789012345678901234567890123456789
  869. //===========================================================================
  870. //    File:    SecurityShell.c
  871. //
  872. //    This file contains a shell for add-on security modules for Apple
  873. //    Remote Access.  This code can be duplicated to write an add-on
  874. //    security code module.
  875. //
  876. //    Copyright © 1992, 1993 Apple Computer Inc.
  877. //    All rights reserved
  878. //
  879. //    Author:  Farzad Sarabi
  880. //
  881. //    Modification history:
  882. //
  883. //    5/10/1993    Farzad        A little cleanup, and added a completion routine.
  884. //                            Some more comments
  885. //    10/6/1992    Farzad        Created
  886. //===========================================================================
  887. #include    "SecurityInterface.h"
  888. // #define SecurityShellVersion 0x0100
  889. //===========================================================================
  890. //    Example of Your Code
  891. //===========================================================================
  892. // function prototypes
  893. static long        DoMyStartup( SecurityReference    MyReference,
  894.                              long                LongParam );
  895. static long        DoMyShutdown( SecurityReference        MyReference,
  896.                               long                    LongParam );
  897. static long        DoMyBegin( SecurityReference    MyReference,
  898.                            long                    LongParam );
  899. static long        DoMyEnd( SecurityReference    MyReference,
  900.                          long                LongParam );
  901. static long        DoMyDataHandler( SecurityReference    MyReference,
  902.                                  long                LongParam );
  903. static long        DoMyAbortHandler( SecurityReference        MyReference,
  904.                                   long                    LongParam );
  905. static long        DoMyTickleHandler( SecurityReference    MyReference,
  906.                                    long                    LongParam );
  907. pascal void        MyCompletionProc( SecurityReference        MyReference,
  908.                                   int                    ResultCode,
  909.                                   void                    * DataPtr,
  910.                                   int                    DataSize,
  911.                                   long                    CompletionParam );
  912. // the following is a shell for your code.  It shows how your entry routine
  913. // should be structured.  Empty supporting routines for the actions are
  914. // provided.
  915. // WARNING:
  916. //        Don't change the name of this routine.  We may change it in the
  917. //        future.  This is the routine ARA expects and calls.
  918. pascal long        MySecurityProcEntry( SecurityActions        Action,
  919.                                      SecurityReference        MyReference,
  920.                                      long                    LongParam )
  921. //===========================================================================
  922. //    Description:    this is the entry point for the ??? security operation.
  923. //                    It is called by AppleTalk Remote Access to have this
  924. //                    security module perform the given operation.  It
  925. //                    dispatches to a variety of routines based on the
  926. //                    requested action.
  927. //
  928. //    Parameters:        Action                the action to be performed
  929. //                    MyReference            this is a unique value representing
  930. //                                        this instance of this code module.
  931. //                    DataPtr                the data for this action
  932. //                    DataSize            the size of data
  933. //
  934. //    Return Value:    long                result code, nonzero indicates an
  935. //                                        error.  Its value is one of the
  936. //                                        SecurityResultCodes.
  937. //
  938. //    Creation Date:
  939. //
  940. //    Modifications:
  941. //
  942. //===========================================================================
  943. {
  944.     switch ( Action )    {
  945.       case    kSecurityStartup:
  946.         return DoMyStartup( MyReference, LongParam );
  947.       case    kSecurityShutdown:
  948.           return DoMyShutdown( MyReference, LongParam );
  949.       case    kSecurityBegin:
  950.           return DoMyBegin( MyReference, LongParam );
  951.       case    kSecurityEnd:
  952.           return DoMyEnd( MyReference, LongParam );
  953.       case    kSecurityDataAvailable:
  954.         return DoMyDataHandler( MyReference, LongParam );
  955.       case    kSecurityAbort:
  956.         return DoMyAbortHandler( MyReference, LongParam );
  957.       case    kSecurityTickleAction:
  958.           return DoMyTickleHandler( MyReference, LongParam );
  959.     }
  960.     return ( kSecurityUnsupportedAction );
  961. }
  962. static long        DoMyStartup( SecurityReference    MyReference,
  963.                              long                LongParam )
  964. //===========================================================================
  965. //    Description:    this routine handles the kSecurityStartup action.  You
  966. //                    should allocate any memory and setup the working
  967. //                    environment (e.g. A5 world) here.
  968. //
  969. //    Parameters:        MyReference        My unique reference
  970. //                    LongParam        additional information
  971. //
  972. //    Return Value:    long            result code, nonzero indicates error
  973. //
  974. //    Creation Date:
  975. //
  976. //    Modifications:
  977. //
  978. //===========================================================================
  979. {
  980. #pragma unused(MyReference)
  981. #pragma unused(LongParam)
  982.     // this routine is called when the module has just been loaded.  You
  983.     // can preallocate any memory you need.  You are not yet starting any
  984.     // to do what this code resource is responsible for.
  985.     // You can allocate and release memory in this routine.
  986.     return ( kSecurityNoErr );
  987. }
  988. static long        DoMyShutdown( SecurityReference        MyReference,
  989.                               long                    LongParam )
  990. //===========================================================================
  991. //    Description:    this routine handles the kSecurityShutdown action.  You
  992. //                    should release any memory allocated by the DoMyStartup
  993. //                    routine.
  994. //
  995. //    Parameters:        MyReference        My unique reference
  996. //                    LongParam        additional information
  997. //
  998. //    Return Value:    long            result code, nonzero indicates error
  999. //
  1000. //    Creation Date:
  1001. //
  1002. //    Modifications:
  1003. //
  1004. //===========================================================================
  1005. {
  1006. #pragma unused(MyReference)
  1007. #pragma unused(LongParam)
  1008.     // this is the last routine that is called before your code resource
  1009.     // is released.  Just do any cleanup you need to perform.  ARA services
  1010.     // are no longer available.
  1011.     // You can allocate and release memory in this routine.
  1012.     return ( kSecurityNoErr );
  1013. }
  1014. static long        DoMyBegin( SecurityReference    MyReference,
  1015.                            long                    LongParam )
  1016. //===========================================================================
  1017. //    Description:    this routine handles the kSecurityBeing action.  This
  1018. //                    routine should start the operations the code resource
  1019. //                    must do.  For example an authentication code resource
  1020. //                    should start the authentication process.
  1021. //
  1022. //    Parameters:        MyReference        My unique reference
  1023. //                    LongParam        additional information
  1024. //
  1025. //    Return Value:    long            result code, nonzero indicates error
  1026. //
  1027. //    Creation Date:
  1028. //
  1029. //    Modifications:
  1030. //
  1031. //===========================================================================
  1032. {
  1033. #pragma unused(MyReference)
  1034. #pragma unused(LongParam)
  1035.     // This routine is called to actually start the code resource to do
  1036.     // what it's responsible for.  E.g. an authentication code resource
  1037.     // should start the authentication process.  A configuration module
  1038.     // can start displaying a dialog etc.
  1039.     // You can allocate and release memory in this routine.
  1040.     return ( kSecurityNoErr );
  1041. }
  1042. static long        DoMyEnd( SecurityReference    MyReference,
  1043.                          long                LongParam )
  1044. //===========================================================================
  1045. //    Description:    this routine handles the kSecurityEnd action.  The action
  1046. //                    is sent to signal the end of the operation the code
  1047. //                    resource was created to do.
  1048. //
  1049. //    Parameters:        MyReference        My unique reference
  1050. //                    LongParam        additional information
  1051. //
  1052. //    Return Value:    long            result code, nonzero indicates error
  1053. //
  1054. //    Creation Date:
  1055. //
  1056. //    Modifications:
  1057. //
  1058. //===========================================================================
  1059. {
  1060. #pragma unused(MyReference)
  1061. #pragma unused(LongParam)
  1062.     // This routine is called when the code resource is finished.  It is
  1063.     // called as a result of you calling ARAAllowUser, ARADontAllowUser,
  1064.     // ARACompleteOperation, or after ARA aborts your code resource.
  1065.     // You could for example cleanup any outstanding asynch calls to the
  1066.     // Mac OS.  ARA services are no longer available.
  1067.     // You can allocate and release memory in this routine.
  1068.     return ( kSecurityNoErr );
  1069. }
  1070. static long        DoMyDataHandler( SecurityReference    MyReference,
  1071.                                  long                LongParam )
  1072. //===========================================================================
  1073. //    Description:    this routine handles the kSecurityDataAvailable action.
  1074. //                    The action is sent when data has arrived for the code
  1075. //                    resource.
  1076. //
  1077. //    Parameters:        MyReference        My unique reference
  1078. //                    LongParam        additional information
  1079. //
  1080. //    Return Value:    long            result code, nonzero indicates error
  1081. //
  1082. //    Creation Date:
  1083. //
  1084. //    Modifications:
  1085. //
  1086. //===========================================================================
  1087. {
  1088. #pragma unused(MyReference)
  1089. #pragma unused(LongParam)
  1090.     // This routine is not used in this release of the ARA Add-on Security.
  1091.     // In future releases we may use this to indicate data being available
  1092.     // for you.  ARA may in the future send events to a modeless dialog
  1093.     // box using the DataAvailable message.
  1094.     // You can allocate and release memory in this routine.
  1095.     return ( kSecurityNoErr );
  1096. }
  1097. static long        DoMyAbortHandler( SecurityReference        MyReference,
  1098.                                   long                    LongParam )
  1099. //===========================================================================
  1100. //    Description:    this routine handles the kSecurityAbort action.  The
  1101. //                    abort action is sent when the code resources operation
  1102. //                    needs to be terminated abnormally.
  1103. //
  1104. //    Parameters:        MyReference        My unique reference
  1105. //                    LongParam        additional information
  1106. //
  1107. //    Return Value:    long            result code, nonzero indicates error
  1108. //
  1109. //    Creation Date:
  1110. //
  1111. //    Modifications:
  1112. //
  1113. //===========================================================================
  1114. {
  1115. // you can remove the unused pragma for any of the parameters you use
  1116. #pragma unused(MyReference)
  1117. #pragma unused(LongParam)
  1118.     // This routine is called when the code resource is being aborted.
  1119.     // You should not make any more calls to ARA services, and you should
  1120.     // start your abort process.  You will receive the End and Shutdown
  1121.     // actions a little while later.
  1122.     // You can allocate and release memory in this routine.
  1123.     return ( kSecurityNoErr );
  1124. }
  1125. static long        DoMyTickleHandler( SecurityReference    MyReference,
  1126.                                    long                    LongParam )
  1127. //===========================================================================
  1128. //    Description:    this routine handles the kSecurityTickle action.  ARA
  1129. //                    sends this action periodically.  The action is also
  1130. //                    generated as a result of a call to ARATickleMe routine.
  1131. //                    
  1132. //
  1133. //    Parameters:        MyReference        My unique reference
  1134. //                    LongParam        When ARA calls this value will be 0,
  1135. //                                    otherwise it is the value passed to
  1136. //                                    the ARATickleMe routine.
  1137. //
  1138. //    Return Value:    long            result code, nonzero indicates error
  1139. //
  1140. //    Creation Date:
  1141. //
  1142. //    Modifications:
  1143. //
  1144. //===========================================================================
  1145. {
  1146. // you can remove the unused pragma for any of the parameters you use
  1147. #pragma unused(MyReference)
  1148. #pragma unused(LongParam)
  1149.     // ARA calls this routine periodically.  You can also initiate a call
  1150.     // to this routine by calling ARATickleMe.  When ARA calls this
  1151.     // routine the LongParam value will be 0 (zero).  When it is called as
  1152.     // a result of a call to ARATickleMe the LongParam will have the value
  1153.     // you passed to ARATickleMe.
  1154.     // You can allocate and release memory in this routine.
  1155.     return ( kSecurityNoErr );
  1156. }
  1157. pascal void        MyCompletionProc( SecurityReference        MyReference,
  1158.                                   int                    ResultCode,
  1159.                                   void                    * DataPtr,
  1160.                                   int                    DataSize,
  1161.                                   long                    CompletionParam )
  1162. //===========================================================================
  1163. //    Description:    this is an example of your a completion routine you can
  1164. //                    use for calls to asynch ARA services.  You can use one
  1165. //                    completion proc and distinguish the reason it was called
  1166. //                    by the value passed in the CompletionParam.
  1167. //                    
  1168. //
  1169. //    Parameters:        MyReference        your unique reference
  1170. //                    ResultCode        result of the asynch ARA call you made
  1171. //                    DataPtr            pointer to the data passed to the ARA
  1172. //                                    proc
  1173. //                    DataSize        actual size of the data
  1174. //                    CompletionParam    additional information you provided 
  1175. //                                    to the ARA service proc
  1176. //
  1177. //    Return Value:    none
  1178. //
  1179. //    Creation Date:
  1180. //
  1181. //    Modifications:
  1182. //
  1183. //===========================================================================
  1184. {
  1185. // you can remove the unused pragma for any of the parameters you use
  1186. #pragma unused(MyReference)
  1187. #pragma unused(ResultCode)
  1188. #pragma unused(DataPtr)
  1189. #pragma unused(DataSize)
  1190. #pragma unused(CompletionParam)
  1191.     // WARNING:
  1192.     //            Do not attempt to allocate or release any memory in this
  1193.     //            routine.  Also don't call any Mac Toolbaox/OS routines 
  1194.     //            that allocate or release memory.  If you need to do this,
  1195.     //            you should call ARATickleMe with a state indicator, and
  1196.     //            allow your DoMyTickle routine to handle it.
  1197.     return;
  1198. }
  1199. Appendix C:  Miscellaneous
  1200. Runtime Environment
  1201. ARA builds an A5 world for a code resource, so the module can have its own global data.  ARA sets the A5 world automatically, prior to calling any routines (entry, completion) in the code resource.
  1202. The module inherits stacks from other executing tasks, and should refrain from recursion and large stack variables.
  1203. The resource file from which the code resources are loaded will be on the top of the resource file stack, when ARA executes code resources.  The security module's resource file is opened as read-only, and you should not attempt to modify or add any resources.
  1204. You must initialize any Toolbox manager's you are using (e.g. InitGraf).
  1205. Building  an Add-on Security Module
  1206. You need MPW 3.2 or later and MPW C to build a security module.  The ARA Security Interface disk contains the files you need to build a security interface.
  1207. The EmptyShell is a good starting point for putting together a code resource.  You can also use the sample module as the starting point for your module.  This code can be used in your security modules, but you must keep Apple's copyrights in the source files.
  1208. After you have designed your security module (e.g. line-level vs. protocol-level and its working behavior), take the "SecurityShell.c" and code the routines that handle the actions.  The Sample Module shows how a protocol-level module that provides a second password is coded.
  1209. You must also define the proper 'sinf' resource for your module.
  1210. After you have compiled the module you must link it with "SecurityInterface.o".  You must also link in "Runtime.o" (included with MPW).  SecurityInterface.o must be the first file in the link command.  The link command should also have "-m SECURITYINTERFACEENTRYPROC".
  1211. For an example of how a security module is build Review the enclosed Sample Module.
  1212. ARA Security Interface Disk
  1213. The enclosed developer disk contains the interface files and sample modules you can use to build an ARA security module.  This sections describes the contents of this disk.
  1214. The "Empty Shell" folder contains a file you can use to build a code resource file.  It contains place holder routines for processing the ARA actions.
  1215. The "Sample Protocol Module" folder contains the complete source for a security module that provides a second password.  Using this module, you can assign each user a second password.  This is a protocol-level module.  You can use this code as a starting point for building your own module.
  1216. "Security Interfaces" folder contains the various header files for interfacing with ARA.  "SecurityInterface.h", and "SecurityPublic.h" contain all the declarations that your module needs for accessing ARA Service Routines.  "SecurityResInfo.h" contains the flags that are used in the 'sinf' resource.  "SecurityTypes.r" has the resource declarations for a security module.
  1217. "SecurityLibraries" contains "SecurityInterface.o" that must be linked as the first file for each of your code resources.
  1218. ºdˇ ˇˇˇˇd
  1219. d,Times
  1220. .ˇ°dONLNdÅ~ôê+~ì, Palatino°dONLNd≤~Àk*1Apple Remote Access°dONLNdÀ~‰ô*Add-on Security Interface
  1222. °dONLNd0L6Xö(U6Author:  Farzad Sarabi°dONLNdGX6dg* Version 1.0°dONLNdSd6pÖ* November 4, 1993°dONLNddà6î*$+Copyright © 1992, 1993 Apple Computer, Inc.ˇ3Ódˇ ˇˇˇˇd
  1223. d,Times
  1224. .ˇ°dONLNdBN_(KTable of Contents, Palatino
  1226. °dONLNdk6wm(t6 Introduction°dONLNdˇˇ)9 ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ...........°dONLNdˇˇ)1°dONLNd!|6àa(Ö6Overview°dONLNdˇˇ)/ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...............°dONLNdˇˇ)'2°dONLNd,ç6ô™(ñ6Security Module Structure°dONLNdˇˇ)w ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P..................°dONLNdˇˇ)/5°dONLNdHôZ•(¢Z+Module Information Resource ('sinf' ID 200)°dONLNdˇˇ)ƒ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.....°dONLNdˇˇ)6°dONLNdv•Z±«(ÆZCode Resource Structure°dONLNdˇˇ)o ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.......°dONLNdˇˇ)8°dONLNdê±ZΩ(∫Z)User Configuration (UCNF Resource ID 200)°dONLNdˇˇ)… ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...°dONLNdˇˇ)    11°dONLNdΩΩZ…t(ΔZClientE °dONLNd√Ωu…)%-side Protocol (CLPR Resource ID 200)°dONLNdˇˇ)´ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P....°dONLNdˇˇ) 12°dONLNdÏ…Z’v(“ZServerfiÄ°dONLNdÚ…v’)%-side Protocol (SRPR Resource ID 200)°dONLNdˇˇ)™ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.....°dONLNdˇˇ) 13°dONLNd’Z·=(fiZ/Connection Configuration (CCNF Resource ID 200)°dONLNdˇˇ)‰ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P........................°dONLNdˇˇ)>14°dONLNdN·ZÌ'(ÍZ-Client Side Line-level (CLLN Resource ID 200)°dONLNdˇˇ)– ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)R15°dONLNdÚ6˛W(˚6Actions°dONLNdˇˇ)% ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...................°dONLNdˇˇ)116°dONLNdä˛Z
  1227. §(ZkSecurityStartup°dONLNdˇˇ)L ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.....................°dONLNdˇˇ)616°dONLNdû
  1228. Z±(ZkSecurityShutdown°dONLNdˇˇ)[ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...............°dONLNdˇˇ)'16°dONLNd≥Z"ú(ZkSecurityBegin°dONLNdˇˇ)D ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P........................°dONLNdˇˇ)>16°dONLNd≈"Z.ï(+Z kSecurityEnd°dONLNdˇˇ)= ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...........................°dONLNdˇˇ)E16°dONLNd’.Z:√(7ZkSecurityDataAvailable°dONLNdˇˇ)j ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P    .........°dONLNdˇˇ)16°dONLNdÔ:ZFù(CZkSecurityAbort°dONLNdˇˇ)G ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.......................°dONLNdˇˇ);16°dONLNdFZRº(OZkSecurityTickleAction°dONLNdˇˇ)e ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ...........°dONLNdˇˇ)17°dONLNdW6cò(`6ARA Service Routines°dONLNdˇˇ)c ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P..........................°dONLNdˇˇ)C18°dONLNd2cZoÜ(lZARARead°dONLNdˇˇ). ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.°dONLNdˇˇ)19°dONLNd=oZ{â(xZARAWrite°dONLNdˇˇ)0 ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)R21°dONLNdI{Záß(ÑZ
  1229. ARALogMessage°dONLNdˇˇ)N ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P....................°dONLNdˇˇ)422°dONLNdZáZì¢(êZ
  1230. ARACallBackAt°dONLNdˇˇ)I ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P......................°dONLNdˇˇ)923°dONLNdkìZü†(úZ ARAAllowUser°dONLNdˇˇ)G ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.......................°dONLNdˇˇ);24°dONLNd{üZ´∂(®ZARADontAllowUser°dONLNdˇˇ)` ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P
  1231. .............°dONLNdˇˇ)"25°dONLNdè´Z∑ø(¥ZARAReadSecurityData°dONLNdˇˇ)g ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P
  1232. ..........°dONLNdˇˇ)26°dONLNd¶∑Z√’(¿ZARAReadLockSecurityData°dONLNdˇˇ)~ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.°dONLNdˇˇ)27°dONLNd¡√Zœ¬(ÃZARAWriteSecurityData°dONLNdˇˇ)j ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P    .........°dONLNdˇˇ)28°dONLNdŸœZ€…(ÿZARAUnlockSecurityData°dONLNdˇˇ)q ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P......°dONLNdˇˇ)29°dONLNdÚ€ZÁ¶(‰ZARAGetUserInfo°dONLNdˇˇ)N ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P....................°dONLNdˇˇ)430°dONLNdÁZÛô(Z ARATickleMe°dONLNdˇˇ)B ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.........................°dONLNdˇˇ)@31°dONLNdÛZˇ»(¸ZARACompleteOperation°dONLNdˇˇ)o ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.......°dONLNdˇˇ)32°dONLNd+6˜(
  1233. 6+Appendix A:  Security Interface Header File°dONLNdˇˇ)≈ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...................°dONLNdˇˇ)133°dONLNdZ6!‘(6"Appendix B:  Security Module Shell°dONLNdˇˇ)ü ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P..°dONLNdˇˇ)41°dONLNdÄ&62≤(/6Appendix C:  Miscellaneous°dONLNdˇˇ) ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P...............°dONLNdˇˇ)'48°dONLNdû2Z>Ω(;ZRuntime Environment°dONLNdˇˇ)e ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ...........°dONLNdˇˇ)48°dONLNdµ>ZJ(GZ#Building  an Add-on Security Module°dONLNdˇˇ)® ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P................°dONLNdˇˇ)*48°dONLNd‹JZV◊(SZARA Security Interface Disk°dONLNdˇˇ)~ ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P ................................°dONLNdˇˇ)P.°dONLNdˇˇ)49ˇ
  1234. ûdˇ ˇˇˇˇd
  1235. d,     Helvetica
  1236.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1237. °dONLNdB6RÜ(N6 Introduction R4R/
  1239. °dONLNd
  1240. gZs    +$"^This document describes the add-on security interface used in Apple Remote Access (ARA).  Thiså°dONLNdlyZÖ    *`document is written for a security module writer, and explains the ARA interface as seen from an°dONLNdÕãZóΔ*add-on security module.äf°dONLNdÂßZ≥    *WAdd-on security modules (security modules) contain code resources that allow additionalç´°dONLNd=πZ≈    *]methods of authenticating users.  ARA uses passwords and a call-back mechanism as its default÷°dONLNdõÀZ◊    *\security.  If you have a system for identifying a user, you can develop a security module to°dONLNd¯›ZÈ3*/integrate your authentication methods into ARA.⁄°dONLNd(˘Z    *^We have defined two types of security devices.  Devices that sit in front of or behind a modem„–°dONLNdá Z *Pand physically prevent a connection prior to user authentication are called lineìê°dONLNd◊      ( -level security*M°dONLNdÁZ)    (&Z\devices.  Systems that perform their authentication after the ARA server and its client have“Ö°dONLNdD/Z;    *\established a connection are classified as protocol-level security devices.  You can develop°dONLNd°AZM*)security modules for each type of device.°dONLNdÀ]ZiÑ*CThe next section gives a brief overview of add-on security modules.°dONLNdyZÖË*ZThe Security Module Structure section describes a module and its structure in more detail.~‰°dONLNdjïZ°    *^The Code Resources section describes the different kinds of code resources that can exist in a°dONLNd…ßZ≥§*security module.°dONLNd⁄√ZœÁ*ZThe Actions section describes the actions ARA sends to code resources to request services.°dONLNd5flZÎ*^The ARA Service Routines section describes the services that ARA provides to security modules.°dONLNdî˚Zü*IAppendix A is the header file for gaining access to ARA Service Routines.°dONLNdfiZ#]*:Appendix B is an empty shell for building a code resource.d¢°dONLNd3Z?    *WAppendix C contains miscellaneous information about security module's such as a modules°dONLNdqEZQ˙*Zruntime environment, how you can build a module, and the enclosed developer disk contents.
  1241.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;1ˇÓdˇ ˇˇˇˇd
  1242. d,     Helvetica
  1243.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1244. °dONLNdB6Rt(N6Overview R4R/
  1246. µ^°dONLNd    gZs    +$"\A security module is a Macintosh file type 'CLMP'.  The creator is vendor specific.  You can°dONLNdfyZÖÌ*Xrequest a creator for your security module from Apple Developer Technical Support (DTS).<2°dONLNdøïZ°    *_Internally a security module contains a number of special resources.  Every module must containˇˇÎX°dONLNdßZ≥    *_an information resource that describes your modules capabilities.  Additionally your module may'°dONLNdπZ≈    *Ycontain a number of code resources.  These code resources are executed to perform various‘G°dONLNdŸÀZ◊    *_functions (e.g. authentication, configuration) for your security module.  ARA then can use yourìÑ°dONLNd9›ZÈ    *]module to authenticate a user's identity beyond the password mechanism that it contains.  ARA°dONLNdóÔZ˚W*:security modules that are placed in the Extensions folder.
  1247.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;2ˇ'~dˇ ˇˇˇˇd
  1248. d,     Helvetica
  1249.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1251. °dONLNd6ZBÖ(?ZDThe following diagram illustrates the contents of a security module:°ddPro†Ç°‘°d
  1252. dPro    †å
  1253. J|*Á    à"à"à"à"qö8†BùB†8ù8ö8ùB"ù#†ç°ddPro
  1254. °d
  1255. dPro    †åqÕí”ú–ú”í–íÕí–ú"–}†ç°ddPro
  1256. °d
  1257. dPro    †åq8BB888B"#†ç°ddPro
  1258. °d
  1259. dPro    †åqg8lBjBl8j8g8jB"j#†ç°ddPro
  1260. °d
  1261. dPro    †åqöí†úùú†íùíöíùú"ù}†ç°ddPro
  1262. °d
  1263. dPro    †åqÕ8”B–B”8–8Õ8–B"–#†ç°ddPro
  1264. 1Ñè˝    °ñ °ddPro8°öˇ–ˇ‹
  1265. JÄV
  1266. .ˇ‡k§ˇøó°dONLNdˇˇ+(Security Add-on Structure†óˇˇˇˇˇˇ
  1267. J|*Á    1}☠   ˇˇˇˇˇˇˇˇ8†å    à"à"à"à" A䂱˝ˇˇˇˇˇˇ    AÑ‹´ˆ    ˇˇˇˇˇˇˇˇH†ç°ñ °ddPro0°ö˝eˇ¡
  1268. ì
  1269. Ìï°dONLNdˇˇ(
  1270. ïType:    °ddPro0Ä=°dONLNdˇˇ)    °ddPro0°dONLNdˇˇ)'CLMP'
  1271. °ddPro0Ìï°dONLNdˇˇ(ï    Creator:    °ddPro0°dONLNdˇˇ)4vendor specific†ó†å
  1272. J|*Á    à"à"à"à"AΩ‚‰˝ˇˇˇˇˇˇ    A∑‹fiˆ    ˇˇˇˇˇˇˇˇH†ç†å    à"à"à"à"A‚˝ˇˇˇˇˇˇ    AÍ‹ˆ    ˇˇˇˇˇˇˇˇH†ç†å    à"à"à"à"AV‚}˝ˇˇˇˇˇˇ    AP‹wˆ    ˇˇˇˇˇˇˇˇH†ç†å    à"à"à"à"A䂱˝ˇˇˇˇˇˇ    AÉ‹™ˆ    ˇˇˇˇˇˇˇˇH†ç†å    à"à"à"à"AΩ‚‰˝ˇˇˇˇˇˇ    A∂‹›ˆ    ˇˇˇˇˇˇˇˇH†ç°ñ °ddPro0°öˇoˇ 
  1273. êç≠œàΰdONLNdˇˇ(óè Information
  1274. °ddPro0àΰdONLNdˇˇ*        Resource
  1275. °ddPro0àΰdONLNdˇˇ*
  1276.  
  1277. 'sinf' ID 200†ó°ñ °ddPro0°öˇˇ 
  1278. …çfiÿàΰdONLNdˇˇ*'User Configuration
  1279. °ddPro0àΰdONLNdˇˇ*    
  1280. 'UCNF' ID 200†ó°ñ °ddPro0°ö˛flˇ 
  1281. ˆç–àΰdONLNdˇˇ*# Connection
  1282. °ddPro0àΰdONLNdˇˇ*
  1283. Configuration
  1284. °ddPro0àΰdONLNdˇˇ*    
  1285. 'CCNF' ID 200†ó°ñ °ddPro0°ö˛Oˇ 
  1286. \çzÃàΰdONLNdˇˇ*TServer Protocol
  1287. °ddPro0àΰdONLNdˇˇ*    Level
  1288. °ddPro0àΰdONLNdˇˇ*    
  1289. 'SRPR' ID 200†ó°ñ °ddPro0°ö˛ˇ 
  1290. èç≠…àΰdONLNdˇˇ*!Client Protocol
  1291. °ddPro0àΰdONLNdˇˇ*    Level
  1292. °ddPro0àΰdONLNdˇˇ*    
  1293. 'CLPR' ID 200†ó°ñ °ddPro0°ö˝øˇ 
  1294. ¬ç‡ÕàΰdONLNdˇˇ*! Client Line
  1295. °ddPro0àΰdONLNdˇˇ*    Level
  1296. °ddPro0àΰdONLNdˇˇ*    
  1297. 'CLLN' ID 200†ó†å
  1298. J|*Á    à"à"à"à"1å‰óÓˇˇˇˇˇˇ    1ä‚ïÏ    ˇˇˇˇˇˇˇˇ8"å‚"ç‰"ê‚"ë‰"삆ç†å    à"à"à"à"1æ„ ˇˇˇˇˇˇ    1Ω‚…Ô    ˇˇˇˇˇˇˇˇ8    à"à"Q¡‚…Í    ˇˇˇˇˇˇˇˇX    ™U™U™U™UQΩÁ≈Ô    ˇˇˇˇˇˇˇˇX†ç†å    à"à"à"à"1Ò„˝ˇˇˇˇˇˇ    1‚¸Ô    ˇˇˇˇˇˇˇˇ8    à"à"QÙ‚¸Í    ˇˇˇˇˇˇˇˇX    ™U™U™U™UQÁ¯Ô    ˇˇˇˇˇˇˇˇX†ç†å    à"à"à"à"1W„cˇˇˇˇˇˇ    1V‚bÔ    ˇˇˇˇˇˇˇˇ8    à"à"Q[‚bÍ    ˇˇˇˇˇˇˇˇX    ™U™U™U™UQVÁ^Ô    ˇˇˇˇˇˇˇˇX†ç†å    à"à"à"à"1ä„ñˇˇˇˇˇˇ    1ä‚ñÔ    ˇˇˇˇˇˇˇˇ8    à"à"Qé‚ñÍ    ˇˇˇˇˇˇˇˇX    ™U™U™U™UQäÁëÔ    ˇˇˇˇˇˇˇˇX†ç†å    à"à"à"à"1Ω„…ˇˇˇˇˇˇ    1Ω‚…Ô    ˇˇˇˇˇˇˇˇ8    à"à"Q¡‚…Í    ˇˇˇˇˇˇˇˇX    ™U™U™U™UQΩÁƒÔ    ˇˇˇˇˇˇˇˇX†ç†å    à"à"à"à"AI*cˇˇˇˇˇˇ    A˝B$\    ˇˇˇˇˇˇˇˇH†ç†å    à"à"à"à"1IVˇˇˇˇˇˇ    1IU    ˇˇˇˇˇˇˇˇ8    à"à"QIP    ˇˇˇˇˇˇˇˇX    ™U™U™U™UQN U    ˇˇˇˇˇˇˇˇX†ç†å    à"à"à"à"A¢*ºˇˇˇˇˇˇ    A˝ú$∂    ˇˇˇˇˇˇˇˇH†ç†å    à"à"à"à"1§Æˇˇˇˇˇˇ    1¢¨    ˇˇˇˇˇˇˇˇ8"¢"§"    ¢"
  1299. §" ¢†ç°ñ °ddPro0°ö˝e˛ò
  1300. fèÁ°dONLNdˇˇ+Ÿ.Code
  1301. °ddPro0Á°dONLNdˇˇ*    Resource†ó°ñ °ddPro0°ö˝e˛
  1302. ¿ÁhÀ°dONLNdˇˇ(
  1303. ¬Data
  1304. °ddPro0hÀ°dONLNdˇˇ*    Resource†ó†å
  1305. J|*Á    à"à"à"à"1oC∑ãˇˇˇˇˇˇ    1j<≤Ñ    ˇˇˇˇˇˇˇˇ8†ç†å    à"à"à"à"1úú‰‰ˇˇˇˇˇˇ    1óïfl›    ˇˇˇˇˇˇˇˇ8†ç†å    à"à"à"à"1‹C$ãˇˇˇˇˇˇ    1◊<Ñ    ˇˇˇˇˇˇˇˇ8†ç†å    à"à"à"à"1BCäãˇˇˇˇˇˇ    1=<ÖÑ    ˇˇˇˇˇˇˇˇ8†ç†å    à"à"à"à"1uúΩ‰ˇˇˇˇˇˇ    1pï∏›    ˇˇˇˇˇˇˇˇ8†ç†å    à"à"à"à"1®Cãˇˇˇˇˇˇ    1£<ÏÑ    ˇˇˇˇˇˇˇˇ8†ç°d
  1306. dPro    †åqî2ö<ó<ö2ó2î2ó<"ó#†ç°ddPro
  1307. °d
  1308. dPro    †åq«ãÕï ïÕã ã«ã ï" |†ç°ddPro
  1309. °d
  1310. dPro    †åq˙2<˝<2˝2˙2˝<"˝#†ç°ddPro
  1311. °d
  1312. dPro    †åq`2f<c<f2c2`2c<"c#†ç°ddPro
  1313. °d
  1314. dPro    †åqìãôïñïôãñãìãñï"ñ|†ç°ddPro
  1315. °d
  1316. dPro    †åq«2Ã<…<Ã2…2«2…<"…#†ç°ddPro
  1317. °ñ °ddPro(°öˇù˛Œ
  1318. p@ëÉ,Times
  1320. ãÉ°dONLNdˇˇ(wBContains information
  1321. °ddPro(ãÉ°dONLNdˇˇ*about this security
  1322. °ddPro(ãÉ°dONLNdˇˇ*module.  E.g. code °ddPro(ãÉ°dONLNdˇˇ*resource types.†ó°ñ °ddPro(°öˇ]˛P
  1323. ùö÷ÿ œ°dONLNdˇˇ+ZA code resource that
  1324. °ddPro( œ°dONLNdˇˇ*is loaded to provide
  1325. °ddPro( œ°dONLNdˇˇ*an interface for
  1326. °ddPro( œ°dONLNdˇˇ*configuring security
  1327. °ddPro( œ°dONLNdˇˇ* information
  1328. °ddPro( œ°dONLNdˇˇ*for a given user on °ddPro( œ°dONLNdˇˇ*
  1329. the server†ó°ñ °ddPro(°öˇ˛Œ
  1330. ›@ãÉ°dONLNdˇˇ(‰BA code resource that
  1331. °ddPro(ãÉ°dONLNdˇˇ*is loaded to provide
  1332. °ddPro(ãÉ°dONLNdˇˇ*an interface for
  1333. °ddPro(ãÉ°dONLNdˇˇ*configuring security
  1334. °ddPro(ãÉ°dONLNdˇˇ*information for a
  1335. °ddPro(ãÉ°dONLNdˇˇ* connection °ddPro(ãÉ°dONLNdˇˇ*document on the °ddPro(ãÉ°dONLNdˇˇ*client†ó°ñ °ddPro(°ö˛s˛Œ
  1336. C@tãÉ°dONLNdˇˇ*/A code resource that °ddPro(ãÉ°dONLNdˇˇ*is loaded by the °ddPro(ãÉ°dONLNdˇˇ*server during the °ddPro(ãÉ°dONLNdˇˇ*protocol level °ddPro(ãÉ°dONLNdˇˇ*authentication of a °ddPro(ãÉ°dONLNdˇˇ*user†ó°ñ °ddPro(°ö˛+˛P
  1337. vö߀ œ°dONLNdˇˇ+Z This is the code
  1338. °ddPro( œ°dONLNdˇˇ*resource that is °ddPro( œ°dONLNdˇˇ*loaded
  1339. °ddPro( œ°dONLNdˇˇ*on the client side
  1340. °ddPro( œ°dONLNdˇˇ*during protocol
  1341. °ddPro( œ°dONLNdˇˇ*level authentication†ó°ñ °ddPro(°ö˝„˛Œ
  1342. ©@À|ãÉ°dONLNdˇˇ(∞BThis resource is
  1343. °ddPro(ãÉ°dONLNdˇˇ*loaded on the client
  1344. °ddPro(ãÉ°dONLNdˇˇ*side for line level
  1345. °ddPro(ãÉ°dONLNdˇˇ*security devices†ó°ñ °ddPro$°ö˝BˇÂ
  1346. |&
  1347.     ZÌ°dONLNdˇˇ(#|+Copyright © 1992, 1993 Apple Computer, Inc.†ó†É
  1348. d
  1350. .ˇ°dONLNdE:ZF«(CZQThe information resource is described in the module Information Resource section.£±°dONLNdóVZb    *`Each of the code resources provides an entry point.  This is a routine which will be called when∫°dONLNd¯hZt    *YARA needs to execute a code resource.  The entry point routine and the operations it must°dONLNdRzZÜj*=support are described in the Code Resource Structure section.C¯°dONLNdêñZ¢    *_When a code resource is loaded, it will be able to access ARA to request certain services.  ForˇˇÛ°dONLNd®Z¥    *bexample it can have data sent to the remote machine.  These services are provided as routines that°dONLNdS∫ZΔ¸*^can be called from a security module.  They are described in the ARA Service Routines section.
  1351.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;3ˇ¨dˇ ˇˇˇˇd
  1352. d,     Helvetica
  1353.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1355. °dONLNd6ZBå(?ZEThe following diagram is a high level view of a loaded code resource:°ddPro†Ç°‘††°§
  1356.     à"à"à"à""$ı###@####˘##¸E##˙#†£
  1357. JSŸ"$ı#@##˘#¸E#˙†°††°§
  1358. "n#3##ü#†£
  1359. JSŸ"n3#ü†°°d
  1360. dPro    †åqkrnknrn"n˙†ç°ddPro
  1361. ††°§P
  1362. "≈h#—##0#†£
  1363. JSŸ"≈h—#0†°°d
  1364. dPro    †åq5˝<˝959<˝9"Â9 †ç°ddPro
  1365. Aôi∏H°d
  1366. dPro    †åq™\±hÆh±\Æ\™\Æh"ÆÈs†ç°ddPro
  1367. 1¯‚a81â\«Î8ˇˇˇˇˇˇ    1ÅTø„    ˇˇˇˇˇˇˇˇ8°ñ °ddPro0°öˇèˇ€
  1368. êYµï
  1369. .ˇèΩ≈˙„°dONLNdˇˇ+[Apple
  1370. °ddPro0„°dONLNdˇˇ* Remote
  1371. °ddPro0„°dONLNdˇˇ* Access†óˇˇˇˇˇˇ
  1372. JSŸ    Aëa∞    ˇˇˇˇˇˇˇˇH°ñ °ddPro8°öˇfiˇ‰
  1373. JSfK
  1374. Ù°dONLNdˇˇ(UTApple Remote Access
  1375. °ddPro8Ù°dONLNdˇˇ*
  1376. Add-on Security Code Resources†óˇˇˇˇˇˇ
  1377. JSŸ    1⁄Y    ˇˇˇˇˇˇˇˇ8°ñ °ddPro$°ö˛2˛∂
  1378. Δ[Ÿ
  1379.     ™°dONLNdˇˇ(Õ^,Copyright © 1992, 1993 Apple Computer, Inc.
  1380. †ó°ñ °ddPro0°öˇÅ˛°
  1381. ùm¬º
  1382. `fi°dONLNdˇˇ(¶p    Security
  1383. °ddPro0`fi°dONLNdˇˇ* Code °ddPro0`fi°dONLNdˇˇ* Resource†ó°ñ °ddPro0°öˇB˛£
  1384. ‘lí≈J°dONLNdˇˇ(finTypes:
  1385. °ddPro$,
  1386. Courier
  1387.     ≈J*
  1388. 
  1389. °ddPro$≈J°dONLNdˇˇ*    °ddPro$n6°dONLNdˇˇ) Server Protocol-Level
  1390. °ddPro$≈J°dONLNdˇˇ(˘n    °ddPro$n6°dONLNdˇˇ) Client Protocol-Level
  1391. °ddPro$≈J°dONLNdˇˇ(n    °ddPro$n6°dONLNdˇˇ) User Configuration°ddPro$Ì)U
  1392. °ddPro$≈J( n
  1393. °ddPro$≈J°dONLNdˇˇ*        °ddPro$n6°dONLNdˇˇ) Client Line-Level
  1394. °ddPro$≈J°dONLNdˇˇ(n    °ddPro$n6°dONLNdˇˇ) Connection Configuration
  1395. °ddPro$≈J(%n
  1396. °ddPro0
  1397. ≈J* 
  1398. °ddPro0≈J* 
  1399. °ddPro0≈J°dONLNdˇˇ* Supported Actions:
  1400. °ddPro$
  1401.     ≈J*    
  1402. °ddPro$≈J°dONLNdˇˇ*        °ddPro$n6°dONLNdˇˇ) kSecurityStartup
  1403. °ddPro$≈J°dONLNdˇˇ(bn    °ddPro$n6°dONLNdˇˇ) kSecurityShutdown
  1404. °ddPro$≈J°dONLNdˇˇ(kn    °ddPro$n6°dONLNdˇˇ) kSecurityBegin
  1405. °ddPro$≈J°dONLNdˇˇ(tn    °ddPro$n6°dONLNdˇˇ) 
  1406. kSecurityEnd
  1407. °ddPro$≈J°dONLNdˇˇ(|n    °ddPro$n6°dONLNdˇˇ) kSecurityDataAvaialble
  1408. °ddPro$≈J°dONLNdˇˇ(Ön    °ddPro$n6°dONLNdˇˇ) kSecurityAbort
  1409. °ddPro$≈J°dONLNdˇˇ(én    °ddPro$n6°dONLNdˇˇ) kSecurityTickleAction†ó°ñ °ddPro0°öˇˇG
  1410. ˆ€P
  1411. d,°dONLNdˇˇ(ˇfiARA Service Routines†ó°d
  1412. dPro    †å
  1413. JSŸq¢T©`¶`©T¶T¢T¶`"¶·s†ç°ddPro
  1414. °ñ °ddPro$°ö˛·ˇ”
  1415. +`©‹
  1416.     R·°dONLNdˇˇ(3cARARead
  1417. °ddPro$R·°dONLNdˇˇ*        ARAWrite
  1418. °ddPro$R·°dONLNdˇˇ*    ARALogMessage
  1419. °ddPro$R·°dONLNdˇˇ*    ARACallBackAt
  1420. °ddPro$R·°dONLNdˇˇ*    
  1421. ARAAllowUser
  1422. °ddPro$R·°dONLNdˇˇ*ARADontAllowUser
  1423. °ddPro$R·°dONLNdˇˇ*    ARAReadSecurityData
  1424. °ddPro$R·°dONLNdˇˇ*    ARAReadLockSecurityData
  1425. °ddPro$R·°dONLNdˇˇ*    ARAWriteSecurityData
  1426. °ddPro$R·°dONLNdˇˇ*    ARAUnlockSecurityData
  1427. °ddPro$R·°dONLNdˇˇ*ARAGetUserInfo
  1428. °ddPro$R·°dONLNdˇˇ*     ARATickleMe
  1429. °ddPro$R·°dONLNdˇˇ*    ARACompleteOperation
  1430. †ó††°§P
  1431. "Ω`#—##0#†£
  1432. JSŸ"Ω`—#0†°°d
  1433. dPro    †åqÊ-Ú4Ú1Ê-Ê1Ê4Ú1"›1    †ç°ddPro
  1434. ††°§P
  1435. "Ì###@####˘##¸E##˙#†£
  1436. JSŸ"Ì#@##˘#¸E#˙†°††°§P
  1437. "f˛#3##ü#†£
  1438. JSŸ"f˛3#ü†°°d
  1439. dPro    †åqc˛j
  1440. f˛c
  1441. f
  1442. j
  1443. f˛"f˙†ç°ddPro
  1444. †É
  1445. d.ˇ(Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;4ˇÆdˇ ˇˇˇˇd
  1446. d,     Helvetica
  1447.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1448. °dONLNdX6hfl(d6Security Module Structure h4h/
  1450. ⁄°dONLNd}Zâ    +$"`A security module is built by creating a Macintosh file that has a 'CLMP' type.  This is used by?°°dONLNd{èZõ    *]ARA to identify the file as a security module.  The module has to be placed in the Extensionsô;°dONLNdŸ°Z≠    *]folder for ARA to find it.  You can do this by dragging it on top of your system folder after3ˆ°dONLNd7≥Zø    *Yinstalling ARA.  The module's creator is defined by you.  You must request a creator from°dONLNdë≈Z—˙*"Developer Technical Support (DTS).
  1451. Ç°dONLNd¥·ZÌ    *aAdditionally the file must contain at least a 'sinf' resource, and a number of code resources for°dONLNdÛZˇ˛*_performing various operations.  The 'sinf' resource and the code resources are described below.;N°dONLNdvZ    *ZCurrently there are five types of code resources that ARA supports.  They are described in°dONLNd—!Z-i*subK¿°dONLNd‘!j-∞)-sections below.°dONLNdÊ=ZI–(FZSCode resources must have the appropriate type, and their resource ID should be 200.
  1452.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;5ˇbdˇ ˇˇˇˇd
  1453. d,     Helvetica
  1454.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1455. °dONLNd<HJ>(FH+Module Information Resource ('sinf' ID 200) IFI/, Palatino
  1457. ïú°dONLNd,ZZf    +aYour module must have a 'sinf' resource with a resource ID of 200.  The 'sinf' resource describes°dONLNdélZxÚ*#what the module's capabilities are.ã°dONLNd≤àZî    *bIn your resource definition file, you should create a 'sinf' resource, and fill in the appropriatef\°dONLNdöZ¶    *bfields.  The template for the resource is defined in a file named "SecurityTypes.r".  This file is°dONLNdx¨Z∏∏*Rfound on the developer disk.  The following is the template for a 'sinf' resource:,
  1458. Courier°dONLNdÀ√gœ©+
  1459.  type 'sinf'°dONLNd◊√Æœ¥)G{°dONLNd›√%œ˜)w#/* security information resource */°dONLNdŸ~ÂÆ(‚~unsigned°dONLNd ŸΔˆ)Hlongint;°dONLNdŸ%Â)_'/* fflags contains info about module */°dONLNd@Ô~˚®(¯~literal°dONLNdIÔΔ˚ˆ)Hlongint;°dONLNdSÔ%˚Ò)_"/* fsignature identifies module */°dONLNdx˙~Æ(~unsigned°dONLNdÅ˙Δˆ)Hlongint;°dONLNdã˙%y)_/* fversion */°dONLNdú~¥(~    unsigned °dONLNd¶Δˆ)Hlongint;°dONLNd∞%ë)_/* fmin_version */°dONLNd≈~Æ(~unsigned°dONLNdŒΔˆ)Hlongint;°dONLNdÿ%ë)_/* fmax_version */°dONLNdÌ&~2Æ(/~unsigned°dONLNdˆ&Δ2ˆ)Hlongint;°dONLNd&%2ë)_/* fserver_data */°dONLNd1~=Æ(:~unsigned°dONLNd1Δ=ˆ)Hlongint;°dONLNd(1%=ë)_/* fclient_data */°dONLNd=G~S“(P~pstring[ 31 ];°dONLNdOG%Sã)ß/* module name */°dONLNda]gis(fg};º√°dONLNddxZÑ    (ÅZdThe first longint is a set of flags that define what the capabilities of the module are.  The values蟰dONLNd…äZñ    *afor the flags are defined in "SecurityResInfo.h", found on the developer disk.  The values should°dONLNd+úZ®]*:be a combination of the following using the "OR" operator:°dONLNdfæ~ Â+$"kSecurityHasLineLevelƒƒ°dONLNd|º)»‘(≈)%Use this flag if your module is to bet&°dONLNd¢»)‘c*
  1460. used for lineπå°dONLNdØ»c‘‘):-level authentication of aò‡°dONLNd ‘)‡‘(›)%user.  This flag causes the module to{d°dONLNd‡)Ï‘* *be displayed on the client side.  It let's0ï°dONLNdÏ)¯‘* !the user select this module for a䯰dONLNd=¯)‘* $connection document, used to connectt‡°dONLNdb)‘* "to a port with a physical security°dONLNdÖ)H* device.°dONLNdé&~2ˆ(/~kSecurityHasProtocolLevel    äê°dONLNd©$)0‘(-)This flag indicates the module7Í°dONLNd»0)<‘* 'provides protocol level authentication.Sˆ°dONLNdÒ<)H‘* &It can be used in combination with the-\ °dONLNdH)T‘* kSecurityHasServerSide and—0°dONLNd3T)`‘* kSecurityHasClientSide flags toLÏ°dONLNdS`)l‘* #indicate if the module supports the°dONLNdwl)x≤* "client side, server side, or both.°dONLNdõÇ~éË(ã~kSecurityHasServerSide6õ°dONLNd≥Ä)å‘(â)"This flag is set for a module that]»°dONLNd÷å)ò‘* "provides the code resources neededE °dONLNd˘ò)§‘* %for the server side.  Any module that    {°dONLNd§)∞‘* %has code to be executed on the server‘,°dONLNdE∞)º‘* $should set this flag, including user°dONLNdjº)»g* configuration.
  1461.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;6ˇ Bdˇ ˇˇˇˇd
  1462. d,     Helvetica
  1463.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1465. °dONLNd@~LÁ(I~kSecurityHasClientSide6õ°dONLNd>)J‘(G)"This flag is set for a module that¶ °dONLNd;J)V‘* "provides code resources needed forf≤°dONLNd^V)b‘* %the client side.  Any module that has≠°dONLNdÑb)n‘* !code to be executed on the client°dONLNd¶n)z~* should set this flag.°dONLNdΩÑ~êÏ(ç~kSecurityHasUserConfig •°dONLNd’Ç)éª(ã) This flag is used for a protocol!fi°dONLNdıǺé‘)ì-levelM°dONLNd¸é)ö‘(ó)#module that has a code resource for}0°dONLNd ö)¶‘* %configuring users on the server.  Has°dONLNdF¶)≤t* 'UCNF' resource.°dONLNdXº~»
  1466. (≈~kSecurityHasConnectionConfig∂∫°dONLNdv∫)Δº(√)This flag is used for a line!‹°dONLNdí∫ΩΔ’)î-levelM°dONLNdôΔ)“‘(œ)#module that has a code resource forI@°dONLNdΩ“)fi‘* $security configuration on the client°dONLNd‚fi)Í®* side.  Has a 'CCNF' resource.°dONLNdÙ~Î(˝~kSecurityHasUserDialog°dONLNdÚ)˛{(˚)Don't use this flag.°dONLNd.
  1467. ~    (~kSecurityHasConnectionDialog°dONLNdL){()Don't use this flag.÷D°dONLNdc2Z>    (;Z`The second longint is the signature of the module.  This value uniquely identifies your security y°dONLNdƒDZP    *Zmodule.  You should reserve a value through Apple Developer Technical Support (DTS).  ThisπS°dONLNdVZb    *cvalue should be the same as your file's creator, but it can be different.  When they are different,6,°dONLNdÉhZt{*@ARA uses the value defined in the 'sinf' resource.  For protocol§°dONLNd√h|t
  1468. (q| -level modules this signature is°dONLNd‰zZÜW(ÉZ9used to associate a client module with the server module.π^°dONLNdñZ¢    *^The next three longints are version numbers and are only used for protocol level modules.  TheÒ6°dONLNd}®Z¥    *[first field is "fversion" and defines the module's version.  The field after "fversion" areˇˇÈ°dONLNdŸ∫ZΔ5*1"fmin_version", and "fmax_version".  For protocol)°dONLNd
  1469. ∫6Δ    )‹1-level authentication, they are used for checking–¿°dONLNd<ÃZÿ    (’Z^the client module's compatibility with the server's.  The client's "fversion" must be a number°dONLNdõfiZÍy*>between the server module's "fmin_version" and "fmax_version".°dONLNd€˙Z*bThe next two longints, "fserver_data" and "fclient_data", are not used, and should be set to zero.€°dONLNd>Z"    *dThe last field is a Pascal string that is your module's name.  This name is used in dialog boxes and°dONLNd£(Z4*)anywhere your modul'es name is displayed.
  1470.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;7ˇ Ïdˇ ˇˇˇˇd
  1471. d,     Helvetica
  1472.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1473. °dONLNd<HJÿ(FHCode Resource Structure IFI/, Palatino
  1475. °dONLNdZZfÑ+DThe following sub-sections describe the structure of code resources.
  1476. °dONLNd]vHÑΩ(ÄHMySecurityProcEntry
  1478. ëÇ°dONLNdqîZ†    +ZEvery code resource must provide a routine named "MySecurityProcEntry".  This is the entry≈É°dONLNdöZ≤    *bpoint to the code resource.  ARA calls it through the Security Interface.  It should be defined as°dONLNd/∏Zƒ}*follows:,
  1479. Courier°dONLNd8œg€©+
  1480.  pascal long°dONLNdEœΔ€û)_$MySecurityProcEntry( SecurityActions°dONLNdkœŒ€¯(ÿŒAction,°dONLNd|⁄>Ê™(„> SecurityReference°dONLNdê⁄ŒÊ)ê MyReference,°dONLNd¶Â>Ò\(Ó> long°dONLNd∞ÂŒÒ)ê LongParam )Qæ°dONLNdºZ     (    Z`ARA sends actions to your code resources to request it to perform a service.  You should process¥«°dONLNdZ    *^the actions and return control to ARA as quickly as possible.  Actions are defined in the fileΩÊ°dONLNd|$Z0    *eSecurityPublic.h.  The "Actions" section describes actions in detail.  The following is a list of the°dONLNd‚6ZB{*actions:°dONLNdÎNgZ«+
  1481. kSecurityStartup°dONLNd¸YgeÕ* kSecurityShutdown°dONLNddgpª* kSecurityBegin°dONLNdog{Ø* kSecurityEnd°dONLNd*zgÜÒ* kSecurityDataAvailable,°dONLNdBÖgëª* kSecurityAbort°dONLNdQêgúÂ* kSecurityTickleAction4”°dONLNdg∂Z¬    (øZaMyReference is a unique value that defines an instance of the code resource.  It is used when you°dONLNd…»Z‘ô*Jcall any of the ARA Service Routines.  It uniquely identifies your thread.„4°dONLNd‰Z    *_LongParam is used to pass additional information for an action.  Currently it is only used with°dONLNdtˆZæ*kSecurityTickleAction.ß°dONLNdãZ    *aYour entry routine should process the action as soon as possible.  It should not stay go into any¬°dONLNdÌ$Z0    *^loops.  It can post asynchronous calls to ARA and other Toolbox routines, but it should return„$°dONLNdL6ZB    *Lcontrol back to ARA quickly.  YOU MUST RETURN CONTROL BACK TO ARA AS SOON AS°dONLNdôHZTä*    POSSIBLE.0«°dONLNd£dZp    *PYour routine's return value is a result code ARA examines for possible errors inx°dONLNdÙvZÇ    *Q"MySecurityProcEntry".  The possible result codes are "SecurityErrors" defined in°dONLNdFàZîü*L"SecurityPublic.h".  Return "kSecurityNoErr" if  your routine is successful.
  1482. °dONLNdì§H≤Ø(ÆHSecurityInterface.o
  1484. ˘°dONLNd߬ZŒ    +a"SecurityInterface.o" is the glue file that provides the ARA Service Routines.  It must be linkedÃ¥°dONLNd    ‘Z‡    *^with each code resource.  When linking a code resource, you must have "SecurityInterface.o" as
  1485.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;8ˇúdˇ ˇˇˇˇd
  1486. d,     Helvetica
  1487.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1489. @À°dONLNd6ZB    (?Zhthe first file in the linker's object file list.  The MPW linker does not shuffle code.  The entry point°dONLNdiHZT•*Kto "SecurityInterface.o" must become the entry point to your code resource.∂°dONLNdµdZp6*-MPW linker uses the -m option to perform code‰∞°dONLNd‚d6p    )‹,-flow analysis and remove any dead code.  ToTΔ°dONLNdvZÇ    (Z[keep your executable code from being stripped, you must provide the following option in the°dONLNdkàZî∏*linker command line:,
  1490. Courier°dONLNdĆg¨+
  1491. -m SECURITYINTERFACEENTRYPROC
  1492. °dONLNdûªH…∏(≈HCompletion Routine
  1494.  Ÿ°dONLNd±ŸZ    +\Most of the ARA Service Routines are asynchronous.  After an asynch ARA routine finishes, it`°dONLNdÎZ˜    *_informs you code resource by calling a completion routine.  Your completion routine should have°dONLNdn˝Z    À*the following declaration:°dONLNdâg ©+
  1495.  pascal void°dONLNdñΔ ò)_#MyCompletionProc( SecurityReference°dONLNdª∂ ˛) MyReference,°dONLNd–%+C((%  int°dONLNd⁄∂+¯)ë ResultCode,°dONLNdÓ*%6I(3%  void°dONLNd˘*∂6Ú)ë
  1496. * DataPtr,°dONLNd 5%AC(>%  int°dONLNd5∂AÏ)ë    DataSize,°dONLNd(@%LI(I%  long°dONLNd3@∂L)ëCompletionParam )y°dONLNdE[Zg    (dZZYou pass a pointer to your completion routine as one of the parameters to asynchronous ARA°dONLNd†mZy•*Service Routines.íÇ°dONLNd≤âZï    *YMyReference should is the same value passed to "MySecurityProcEntry".  It identifies your°dONLNd õZßÄ*    instance.(t°dONLNd∑Z√    *`ResultCode is the result of the asynchronous ARA Service you had requested.  It will be non zeroÒ⁄°dONLNdw…Z’    *bif the operation failed.  It will contain one of the values in ARAErr defined in SecurityPublic.h.ðdONLNd€€ZÁ    *ZYou should check its value at the start of your completion routine before you do any other°dONLNd6ÌZ˘∞*Mprocessing.  If a read or write times out, the ResultCode will be ARATimeout.ò”°dONLNdÑ    Z    *aDataPtr is the pointer you passed to the asynch ARA Service Routine.  E.g. this will point to the°dONLNdÊZ'√*data read by ARARead.°dONLNd¸7ZC¥*DataSize will be the ∞ °dONLNd7¥CŒ)ZactualR@°dONLNd7œC˙)C size of processed data.  E.g. the number of bytes read by ARARead.‘°dONLNd[SZ_    (\Z_CompletionParam is an additional long you provide.  Its value will be the same value you passed›£°dONLNdªeZq    *`to the asynch ARA Service Routine.  You can use it as a state indicator.  E.g. you can define an    •°dONLNdwZÉ    *aenumeration containing the set of all your states.  When you call an asynch ARA routine, pass theu°dONLNd~âZï    *^state you want to be in when the call is done.  E.g. pass "kFinished1stRead" to ARARead.  When7ñ°dONLNd›õZß    *Yyour completion routine gets called with CompletionParam equal to "kFinished1stRead", theó°dONLNd7≠Zπ    *^ARARead has finished and you can go to the next state.  See the sample module on the developer°dONLNdñøZÀ—*disk for an example of this.
  1497.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú;9ˇ
  1498. dˇ ˇˇˇˇd
  1499. d,     Helvetica
  1500.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1502. ºŒ°dONLNd6ZB    (?ZXYou should not call any Memory Manager routines, or any routines that result in a MemoryÈh°dONLNdYHZT    *ZManager call from a completion routine.  If you need to call these types of routines, call°dONLNd¥ZZfX*7ARATickleMe and handle it in the kSecurityTickleAction.
  1503. °dONLNdÏvHÑ(ÄHRuntime Environment (A5 World)
  1505. bH°dONLNd îZ†    +XAn A5 World is setup for your code resource by ARA.  You don't need to be concerned with´K°dONLNdd¶Z≤    *`initializing or setting up the A5 world in the code resource.  ARA sets up the A5 world prior toˇP°dONLNd≈∏Zƒ    *\executing any of the code resource (entry routine, and completion routines).  Since the code£ı°dONLNd" Z÷    *_resource has an A5 world, it you can have static (global) data and use the data the same way as°dONLNdÇ‹ZËõ*an application.ê°dONLNdí¯Z    *aDuring the execution of your code resource, the resource fork of the security module is open, andò\°dONLNdÙ
  1506. Z    *bit is put on top of the resource forks stack.  The file is opened in read only mode, so you should¯™°dONLNdWZ(    *`not attempt to write any data to the module's resource fork.  A better way of storing data is tog#°dONLNd∏.Z:    *cstore it in a separate preference file, which will not be deleted when you update a user's security°dONLNd@ZL~*module.æI°dONLNd$\Zh    *[You can make calls to Mac Toolbox routines.  Whenever possible you should call asynchronousÛ‡°dONLNdÄnZz    *]routines, so you can return control to ARA.  Furthermore, you should not go into any loops or°dONLNdfiÄZåI*5call SystemTask as a way of returning control to ARA.
  1507. °dONLNdúH™¬(¶HARA Service Routines
  1509. 
  1510. °dONLNd)∫ZΔ    +[ARA provides a number of services accessible through ARA Service Routines.  The header fileP‰°dONLNdÖÃZÿ    *_"SecurityInterface.h" has the declarations for these routines.   To use them you must link with°dONLNdÂfiZÍ∂*"SecurityInterface.o".°dONLNd¸˙ZÄ*DThe ARA Service Routines are described in detail in a later section.
  1511.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú610ˇ¨dˇ ˇˇˇˇd
  1512. d,     Helvetica
  1513.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1514. °dONLNd<HJA(FH)User Configuration (UCNF Resource ID 200) IFI/, Palatino
  1516. »…°dONLNd*ZZf    +ZThis code resource is executed when a user window is open on the ARA server admin, and theìe°dONLNdÖlZx    *^security module's configuration button is selected.  It is used for configuring protocol-level’D°dONLNd‰~Zä    *^security information on a per-user basis.  The code resource should display a modal dialog boxfi¯°dONLNdCêZú    *Rand get any needed information.  It can store 150 bytes of data for each user (see°dONLNdñ¢ZÆF*/ARAWriteSecurityData, and ARAReadSecurityData).ân°dONLNdΔæZ     *^On kSecurityBegin you should start your processing, e.g. request to read the existing securityXt°dONLNd%–Z‹    *Xdata (ARAReadLockSecurityData), or to get the user's name (ARAGetUserInfo).  When you've^˙°dONLNd~‚ZÓ    *^obtained this information, you can call ARATickleMe to put up the modal dialog box (it must beˇˇ˘¥°dONLNd›ÙZ    *ca modal dialog box).  You must display the user's name at the top of this dialog box.  The user cand‹°dONLNdAZ    *cthen input/modify the information and either save or cancel.  If the user selects to save the data,~´°dONLNd•Z$    *_you must write it out by calling ARAWriteSecurityData.  This information will then be available°dONLNd*Z6O*8to the server-side protocol-level authentication module.°dONLNd>FZR©*GThe following ARA Service Routines can be used by a UCNF code resource:,
  1517. Courier°dONLNdÜ^gjµ+
  1518. 
  1519. ARALogMessage°dONLNdîiguŸ* ARAReadSecurityData°dONLNd®tgÄÒ* ARAReadLockSecurityData°dONLNd¿gãÂ* ARAUnlockSecurityData°dONLNd÷ägñfl* ARAWriteSecurityData°dONLNdÎïg°ª* ARAGetUserInfo°dONLNd˙†g¨©* ARATickleMe°dONLNd´g∑fl* ARACompleteOperation
  1520.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú611ˇ2dˇ ˇˇˇˇd
  1521. d,     Helvetica
  1522.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1523. °dONLNd<HJi(FHClient”@°dONLNd<iJE)!%-side Protocol (CLPR Resource ID 200) IFI/, Palatino
  1525. íÆ°dONLNd,ZZf    (cZXThis code resource is executed on the ARA client for protocol-level authentication.  The(j°dONLNdÖlZx    *[corresponding server-side protocol-level module is also executed on the server, and the two°dONLNd·~Zä*)module's can communicate with each other.ÃD°dONLNd öZ¶    *^The client module's state should be driven by the server, and when the authentication has been[F°dONLNdj¨Z∏    *Wcompleted, both sides should call ARAAllowUser/ARADontAllowUser, so ARA can progress to°dONLNd¬æZ ñ*the next state.£Æ°dONLNd“⁄ZÊ    *OA CLPR module can pass a maximum of 500 bytes of data to ARAWrite/ARARead.  The”Ú°dONLNd"ÏZ¯    *XARAWrite and ARARead will communicate with the server-side protocol (i.e. ARARead on the°dONLNd{˛Z
  1526. O*9client side will read data written by the server module).°dONLNdµZ&    *\On kSecurityBegin you should start your state machine, getting information from the user and€˙°dONLNd,Z8    *\sending it to the server module.  The server module should inform the client module when theí°dONLNdo>ZJ    *Puser is authenticated or rejected, at which time it should call ARAAllowUser, or°dONLNd¿PZ\π*ARADontAllowUser.°dONLNd“lZx¶*GThe following ARA Service Routines can be used by a CLPR code resource:,
  1527. Courier°dONLNdÉgèë+
  1528. ARARead°dONLNd"égöó* ARAWrite°dONLNd+ôg•µ*
  1529. ARALogMessage°dONLNd9§g∞Ø* ARAAllowUser°dONLNdFØgª«* ARADontAllowUser°dONLNdW∫gΔ©* ARATickleMe°dONLNdc≈g—fl* ARACompleteOperation
  1530.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú612ˇ    îdˇ ˇˇˇˇd
  1531. d,     Helvetica
  1532.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1533. °dONLNd<HJm(FHServerŸ¿°dONLNd<mJJ)%%-side Protocol (SRPR Resource ID 200) IFI/, Palatino
  1535. 7®°dONLNd,ZZf    (cZ^This code resource is executed on the server to authenticate a user after the ARA protocol has“ °dONLNdãlZx    *[been established.  It can communicated with the corresponding client authentication module.°dONLNdË~Zä**ARA loads the client module automatically.∏9°dONLNdöZ¶    *^This code resource should get the user information from the client module and determine if theHL°dONLNdr¨Z∏    *^user should be allowed in.  Once a user has been authenticated or rejected, this code resourceÿŒ°dONLNd—æZ     *Wshould inform the client side, and then call ARAAllowUser/ARADontAllowUser.  The client°dONLNd)–Z‹ã*=code resource should also call ARAAllowUser/ARADontAllowUser.ÔG°dONLNdgÏZ¯    *XA SRPR code resource can write and read a maximum of 500 bytes of data using ARAWrite or°dONLNd¿˛Z
  1536. I*3ARARead.  The data is exchanged with client module.
  1537. ï°dONLNdÙZ&    *HThis code resource can use ARAReadLockSecurityData, ARAReadSecurityData,âÊ°dONLNd=,Z8    *UARAWriteSecurityData, and ARAUnlockSecurityData to access and modify the 150 bytes of
  1538. k°dONLNdì>ZJ    *bsecurity data associated with each user.  Each security module can have 150 bytes of data for each°dONLNdˆPZ\o*user.°dONLNd¸lZx§*GThe following ARA Service Routines can be used by a SRPR code resource:,
  1539. Courier°dONLNdDÉgèë+
  1540. ARARead°dONLNdLégöó* ARAWrite°dONLNdUôg•µ*
  1541. ARALogMessage°dONLNdc§g∞µ*
  1542. ARACallBackAt°dONLNdqØgªØ* ARAAllowUser°dONLNd~∫gΔ«* ARADontAllowUser°dONLNdè≈g—Ÿ* ARAReadSecurityData°dONLNd£–g‹Ò* ARAReadLockSecurityData°dONLNdª€gÁÂ* ARAUnlockSecurityData°dONLNd—ÊgÚfl* ARAWriteSecurityData°dONLNdÊÒg˝ª* ARAGetUserInfo°dONLNdı¸g”* ARAGetMySessionRef°dONLNdg©* ARATickleMe°dONLNdgfl* ARACompleteOperation
  1543.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú613ˇdˇ ˇˇˇˇd
  1544. d,     Helvetica
  1545.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1546. °dONLNd<HJi(FH/Connection Configuration (CCNF Resource ID 200) IFI/, Palatino
  1548. 2†°dONLNd0ZZf    +]A Connection Configuration code resource is executed on the client side when the user selects{˘°dONLNdélZx    *b"Configuration" button on the client in a connection document's security option.  It can store 150°dONLNdÒ~Zäê*Hbytes of data in a connection document for a line-level security device.ч°dONLNd:öZ¶    *`It should display a modal dialog and get any information relevant to connections with line-level£P°dONLNdõ¨Z∏    *Dsecurity.  You can use ARAReadLockSecurityData, ARAReadSecurityData,°dONLNd‡æZ ˜*WARAWriteSecurityData, and ARAUnlockSecurityData to access and modify the security data.πD°dONLNd8⁄ZÊ    *^On kSecurityBegin you should get the existing security data.  Once you have obtained the data,Û°dONLNdóÏZ¯    *ayou should display a dialog box, and allow the user to modify it.  When the user is done, you can°dONLNd˘˛Z
  1549. ò*Gwrite the security data if it was modified, using ARAWriteSecurityData.°dONLNdAZ&®*GThe following ARA Service Routines can be used by a CCNF code resource:,
  1550. Courier°dONLNdâ1g=Ÿ+
  1551. ARAReadSecurityData°dONLNdù<gHÒ* ARAReadLockSecurityData°dONLNdµGgSÂ* ARAUnlockSecurityData°dONLNdÀRg^fl* ARAWriteSecurityData°dONLNd‡]gi©* ARATickleMe°dONLNdÏhgtfl* ARACompleteOperation
  1552.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú614ˇ    Ídˇ ˇˇˇˇd
  1553. d,     Helvetica
  1554.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1555. °dONLNd<HJL(FH-Client Side Line-level (CLLN Resource ID 200) IFI/, Palatino
  1557. å°dONLNd.ZZf    +dA client-side line-level code resource is executed after a physical connection has been established,y‚°dONLNdìlZx*Zusing a connection document configured with security.  It should communicate with the line°⁄°dONLNdÌlx    (u-°dONLNdÓ~Zäõ(áZIlevel device, prompting the user for any information the device requires.p@°dONLNd8öZ¶    *XA CLLN code resource can use the ARARead and ARAWrite to communicate with the line-levelÔê°dONLNdë¨Z∏    *`device on the server.  The data being read or written is sent over the physical line without any
  1558. n°dONLNdÚæZ     *bpacketization.  Your code resource gets control of the line after a connection is established, but°dONLNdU–Z‹ï*Fbefore your authentication device allows connection to the ARA server.Sh°dONLNdúÏZ¯    *_On kSecurityBegin you should start the communication process with the server line-level device.ó°dONLNd˝˛Z
  1559.     *_You can display a dialog box to obtain information from the user.  Once the physical device hasC®°dONLNd]Z    *Pauthenticated or rejected the user the code resource should call ARAAllowUser or°dONLNdÆ"Z._*9ARADontAllowUser to let ARA transition to the next state.:Ç°dONLNdË>ZJ    *XYou can use ARAReadSecurityData to access the 150 bytes of data stored in the connectionÀ©°dONLNdAPZ\    *[document.  You can not modify this information during authentication.  The security data isê°dONLNdùbZn    *astored in an alias to a remote server as well as the original connection document, so you can get°dONLNdˇtZÄ¢*Nthe data even if the connection is initiated from an alias to a remote server.°dONLNdNêZúá*@A CLLN code resource can use the following ARA Service Routines:,
  1560. Courier°dONLNdèßg≥ë+
  1561. ARARead°dONLNdó≤gæó* ARAWrite°dONLNd†Ωg…Ø* ARAAllowUser°dONLNd≠»g‘«* ARADontAllowUser°dONLNdæ”gflŸ* ARAReadSecurityData°dONLNd“figÍ©* ARATickleMe°dONLNdfiÈgıfl* ARACompleteOperation
  1562.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú615ˇ ˙dˇ ˇˇˇˇd
  1563. d,     Helvetica
  1564.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1565. °dONLNdB6Rf(N6Actions R4R/
  1567. $¯°dONLNdgZs    +$"_Actions are one of the parameters passed to your code resource's entry routine.  ARA sends them°dONLNdhyZÖ *-to request a service from your code resource.hí°dONLNdóïZ°    *^All actions are sent during main thread time, so you can allocate memory and make calls to Mac°dONLNdˆßZ≥    *\Toolbox routines.  The code resource's A5 world is setup prior to calling your routine.  The°dONLNdSπZ≈ì*Gresource fork of your module is open and on top of the resources stack.ã®°dONLNdõ’Z·    *XYou should process actions as quickly as possible.  You should not go into loops and use°dONLNdÙÁZÛd*;SystemTask calls as a way of returning control back to ARA.
  1568. °dONLNd0˘H®(HkSecurityStartup F/
  1570. AP°dONLNdAZ#    +^kSecurityStartup is sent immediately after your code resource is loaded.  You can allocate any"Z°dONLNd†)Z5    *_needed memory during the processing of this action, but you should not make any calls to any ofÒ,°dONLNd;ZG    *[the ARA Service Routines.  Once processed, you should return kSecurityNoErr.  Generally you°dONLNd\MZY8*2should use kSecurityBegin to start any processing.
  1571. °dONLNdè_Hm∑(iHkSecurityShutdown lFl/
  1573. ;D°dONLNd°}Zâ    +ZkSecurityShutdown is the last action sent prior to unloading your code resource.  The codeG*°dONLNd¸èZõ    *^resource will not be called any more after this action.  You can release any allocated memory.ÙÄ°dONLNd\°Z≠    *ZMake sure you have cleaned everything up before returning.  You can not use any of the ARA°dONLNd∑≥Zø!**Service Routines during kSecurityShutdown.
  1574. °dONLNd‚≈H”ü(œHkSecurityBegin “F“/
  1576.  §°dONLNdÒ„ZÔ    +akSecurityBegin is sent to request your code resource to perform its operation.  E.g. requesting a4°dONLNdSıZ~*protocolp@°dONLNd[ı    )%[-level module to authenticate a user.  The code resource should start the operation that itYP°dONLNd∑Z    (Z_is responsible for.  You can allocate memory and other needed resources.  You can also call ARA°dONLNdZ%Ó* Service Routines asynchronously.
  1577. °dONLNd8+H9î(5H kSecurityEnd 8F8/
  1579. år°dONLNdEIZU    +\kSecurityEnd is sent when the operations that the resource performs are being finished.  Youˇˇ˘V°dONLNd¢[Zg%*.should do your cleanup at this time.  You can Üú°dONLNd–[%g3)Ànot‹°dONLNd”[4g    )0 make any calls to ARA Service Routines after or°dONLNdmZy™(vZduring this action.
  1580. °dONLNdHçÃ(âHkSecurityDataAvailable åFå/
  1582. °dONLNd/ùZ©R+9kSecurityDataAvailable is not being used in this release.
  1583.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú616ˇ    dˇ ˇˇˇˇd
  1584. d,     Helvetica
  1585.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1586. °dONLNd6HDù(@HkSecurityAbort CFC/, Palatino
  1588. ˜Ñ°dONLNdTZ`    +]kSecurityAbort is sent when the operation of your code resource is being aborted.  You shouldç°dONLNdmfZr    *^stop any further processing by your code resource (including in your completion routine.  E.g.zÚ°dONLNdÃxZÑ    *`through the use of a flag).  Your code resource should terminate any outstanding asynch calls toˇˇ¯‡°dONLNd-äZñ    *^routines other than ARA Service Routines.  Outstanding ARA Service Routines will be aborted by°dONLNdåúZ®r*ARA.
  1589. °dONLNdëÆHº≈(∏HkSecurityTickleAction ªFª/
  1591. VL°dONLNdßÃZÿ    +YkSecurityTickleAction is sent to your code resource periodically.  You can also request a2&°dONLNdfiZÍ    *RkSecurityTickleAction explicitly by calling the ARATicleMe routine.  When you calln¿°dONLNdTZ¸    *[ARATickleMe you pass an additional parameter which is sent to your "MySecurityProcEntry" as&°dONLNd∞Z    *athe LongParam.  This additional parameter can be used as a state indicator.  E.g. an asynchronous=P°dONLNdZ     *`call has finished, so from your completion routine you call ARATickleMe with the state indicatorˇˇ˝ °dONLNds&Z2    *_"DidMyAsynchCall" (this can be a value in an enum).  In processing of kSecurityTickleAction youhÇ°dONLNd”8ZD    *\check the LongParam to see if it matches "DidMyAsynchCall".  If it matches you know you have n°dONLNd0JZV    *_finished your asynchronous operation and are ready to transition to the next state.  You should°dONLNdê\Zh    *Zalso do an ARATickleMe when you need to perform main thread time operations (e.g. allocatel˝°dONLNdÎnZz    *\memory) .  When kSecurityTickleAction is being sent periodically by ARA LongParam will be 0.|≥°dONLNdIÄZå    *VFor an example on the use of kSecurityTickleAction and ARATickleMe refer to the Sample°dONLNd†íZû~*module.
  1592.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú617ˇ&dˇ ˇˇˇˇd
  1593. d,     Helvetica
  1594.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1595. °dONLNdB6R≈(N6ARA Service Routines R4R/
  1597. Δå°dONLNdgZs    +$"\ARA Service Routines are a set of functions that code resources have access to.  Using thesexÓ°dONLNdryZÖ    *Zroutines, code resources can request ARA services.  The following is a list of ARA Service°dONLNdÕãZóÉ*    Routines:,
  1598. Courier°dONLNd◊≥gøë+
  1599. (ARARead°dONLNdflæg ó* ARAWrite°dONLNdË…g’µ*
  1600. ARALogMessage°dONLNdˆ‘g‡µ*
  1601. ARACallBackAt°dONLNdflgÎØ* ARAAllowUser°dONLNdÍgˆ«* ARADontAllowUser°dONLNd"ıgŸ* ARAReadSecurityData°dONLNd6g Ò* ARAReadLockSecurityData°dONLNdN gfl* ARAWriteSecurityData°dONLNdcg"Â* ARAUnlockSecurityData°dONLNdy!g-ª* ARAGetUserInfo°dONLNdà,g8©* ARATickleMe°dONLNdî7gCfl* ARACompleteOperation°dONLNd©RZ^S([Z9The following sub-sections describe each of the routines.
  1602. °dONLNdÂnH|b(xHNote
  1604. pâ°dONLNdÍåZò    +LAll of the routines expect a MyReference parameter.  This value is passed to7P°dONLNd7ûZ™    *["MySecurityProcEntry", and is a unique value representing the instance of the security code°dONLNdì∞ZºÇ*    resource.
  1605.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú618ˇ
  1606. ñdˇ ˇˇˇˇd
  1607. d,     Helvetica
  1608.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1609. °dONLNdRH`(\HARARead _F_/, Palatino°dONLNdpH~m*Syntax,
  1610. Courier
  1612. °dONLNdägñµ+
  1613. pascal ARAErr°dONLNdäΔñb)_ARARead( SecurityReference°dONLNd9äÖñÕ)ø MyReference,°dONLNdL(ûˆ void°dONLNdVïÖ°¡)è
  1614. * DataPtr,°dONLNdg†ˆ¨(©ˆ int°dONLNdp†Ö¨ª)è    DataSize,°dONLNdÄ´ˆ∑Ä(¥ˆ SecurityCompletionProc°dONLNdò´Ö∑fl)èCompletionProc,°dONLNdÆ∂ˆ¬(øˆ long°dONLNd∏∂Ö¬Ò)èCompletionParam );
  1615. °dONLNdÀ—Hflà(€H Description
  1617.     Ô°dONLNd◊ÔZ˚    +^This routine is used to issue an asynchronous read call to ARA.  The read will complete eitherÁ*°dONLNd6Z
  1618.     *]when ARA times out, or the number of bytes requested is read.  This read is used to read dataÒ∑°dONLNdîZ*[coming from the remote machine.  The protocol-level modules read from each other.  The lineä9°dONLNdÔ    (-°dONLNd%Z1@(.Z4level module reads from a device on the server side.
  1619. °dONLNd%AHOÑ(KH
  1620. Parameters
  1622. °dONLNd0_Zkº+QMyReference is the unique identifier passed to the code resource's entry routine.M
  1623. °dONLNdÇ{Zá    *_DataPtr points to a location where the data will be read to.  It must not be released while the°dONLNd‚çZô*$asynchronous read has not completed.|≥°dONLNd©Zµ    *\DataSize is the maximum number of bytes to be read to DataPtr.  The maximum data size is 500°dONLNddªZ«s*bytes.fÑ°dONLNdk◊Z„    *^CompletionProc is a function pointer you provide to be called when the read operation has been°dONLNd ÈZı˛*]completed.  If a time-out occurs the CompletionProc is called with a kARATimeout result code.T∫°dONLNd(Z    *UCompletionParam is additional information you can provide which will be passed to the°dONLNd~Z#§*CompletionProc.
  1624. °dONLNdé3HAë(=H Return Value
  1626. °dONLNdõQZ]fl+UResult code.  Non kARANoErr result codes are usually because the call was not queued.
  1627. °dONLNdÒmH{b(wHNote
  1629. U“°dONLNdˆãZó    +aThis is an asynchronous call and can be called during interrupt time.  The DataPtr field must not°dONLNdXùZ©
  1630. *)be released until the call has completed.
  1631.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú619ˇBdˇ ˇˇˇˇd
  1632. d,     Helvetica
  1633.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1634. °dONLNd6HDw(@HSee Also
  1636. °dONLNd    TZ`â+ARAWrite
  1637.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú620ˇ
  1638. @dˇ ˇˇˇˇd
  1639. d,     Helvetica
  1640.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1641. °dONLNdHHV(RHARAWrite UFU/, Palatino°dONLNd    fHtm*Syntax,
  1642. Courier
  1644. °dONLNdÄgåµ+
  1645. pascal ARAErr°dONLNdÄΔåh)_ARAWrite( SecurityReference°dONLNd<ÄùåÂ)◊ MyReference,°dONLNdOãˆó( void°dONLNd[ãùóŸ)ß
  1646. * DataPtr,°dONLNdlñˆ¢(üˆ  int°dONLNdwñù¢”)ß    DataSize,°dONLNdá°ˆ≠Ü(™ˆ  SecurityCompletionProc°dONLNd†°ù≠˜)ßCompletionProc,°dONLNd∂¨ˆ∏(µˆ  long°dONLNd¬¨ù∏    )ßCompletionParam );
  1647. °dONLNd’«H’à(—H Description
  1649. ¡Ã°dONLNd·ÂZÒÆ+KThis routine can be used to write data to the remote machine.  For protocolà°dONLNd,ÂØÒ
  1650. (ÓØ-level authenticationf°dONLNdB˜Zf(Z>the data is transferred over a reliable link, whereas for line;<°dONLNdĘg    (g&-level authentication the data is justrç°dONLNdß    Z    (Z`transferred over the connection without any packetization.  Protocol-level modules write to each°dONLNdZ'ë*Iother.  Line-level modules write to a security device on the server side.
  1651. °dONLNdR7HEÑ(AH
  1652. Parameters
  1654. °dONLNd]UZaº+PMyReference is the unique reference passed to the code resource's entry routine.°dONLNdÆqZ}0*3DataPtr is a pointer to the data to be written out.°dONLNd‚çZô⁄*VDataSize is the number of bytes to be written.  A maximum of 500 bytes can be written.(°dONLNd9©Zµ    *`CompletionProc is a pointer to a completion routine which will be called when the write has been°dONLNdöªZ«ã*
  1655. completed.T∫°dONLNd•◊Z„    *UCompletionParam is additional information you can provide which will be passed to the°dONLNd˚ÈZı§*CompletionProc.
  1656. °dONLNd Hë(H Return Value
  1658. °dONLNd#Z/±+NResult code.  Errors are usually caused when the write call can not be queued.
  1659. °dONLNdg?HMb(IHNote
  1661. ’5°dONLNdl]Zi    +`This is an asynchronous call and can be called at interrupt time.  The DataPtr field must not be°dONLNdÕoZ{*+released until the call has been completed.
  1662. °dONLNd˘ãHôw(ïHSee Also
  1664. °dONLNd©ZµÜ+ARARead
  1665.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú621ˇfidˇ ˇˇˇˇd
  1666. d,     Helvetica
  1667.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1668. °dONLNdHHV™(RH
  1669. ARALogMessage UFU/, Palatino°dONLNdfHtm*Syntax,
  1670. Courier
  1672. °dONLNdÄgå•+5extern pascal ARAErr ARALogMessage( SecurityReference°dONLNdKÄ∂å˛(â∂ MyReference,°dONLNd`ã%óU(î%    char°dONLNdlã∂óÚ)ë
  1673. * Message,°dONLNdñ%¢!(ü%*    SecurityCompletionProc CompletionProc,°dONLNd≤°%≠U*     long°dONLNdæ°∂≠")ëCompletionParam );
  1674. °dONLNd—«H’à(—H Description
  1676. °dONLNd›ÂZÒè+FYou can use this routine to have a message logged to the ARA log file.
  1677. °dONLNd$HÑ( H
  1678. Parameters
  1680. °dONLNd/Z+g+@Message is a Pascal string which will be stored in the log file.
  1681. °dONLNdp;HIë(EH Return Value
  1683. °dONLNd}YZeè+ Result code.
  1684. °dONLNdäuHÉb(HNote
  1686. °dONLNdèìZüá+DThis is an asynchronous call that can be made during interrupt time.
  1687.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú622ˇ
  1688. 6dˇ ˇˇˇˇd
  1689. d,     Helvetica
  1690.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1691. °dONLNdRH`°(\H
  1692. ARACallBackAt _F_/, Palatino°dONLNdpH~m*Syntax,
  1693. Courier
  1695. °dONLNdägñ{+.pascal ARAErr ARACallBackAt( SecurityReference°dONLNdEäùñÂ(ìù MyReference,°dONLNdX(ûˆ  °dONLNd[ï°,) char°dONLNdeïù°Î)è
  1696. * DialString,°dONLNdy†ˆ¨ò(©ˆ     SecurityCompletionProc°dONLNdï†ù¨˜)ßCompletionProc,°dONLNd´´ˆ∑,(¥ˆ         long°dONLNdπ´ù∑    )ßCompletionParam );
  1697. °dONLNdÃΔH‘à(–H Description
  1699. Ñ°dONLNdÿ‰Z    +^This routine can be used to change the phone number which ARA will call back at.  In order fori–°dONLNd7ˆZ    *^this routine to work the call-back must be enabled for the given user.  The call-back won't be°dONLNdñZ”*executed until all other add`°dONLNd≤‘å)z(-on security modules have been executed.ÑÓ°dONLNd€$Z0    (-Z]The new number is only used for the current session, and won't change the permanent call-back°dONLNd96ZB*number.
  1700. °dONLNdARH`Ñ(\H
  1701. Parameters
  1703. ®|°dONLNdLpZ|    +`DialString is a Pascal string which contains the phone number to dial.  It must be a valid phone°dONLNd≠ÇZé*number.°dONLNdµûZ™    *WCompletionProc is a routine pointer which will be called when the phone number has been°dONLNd
  1704. ∞Zº4*0assigned (not when the call-back has been made).Ô§°dONLNd>ÃZÿ    *XCompletionParam can contain additional information you can supply to be passed on to the°dONLNdófiZͧ*CompletionProc.
  1705. °dONLNdß˙Hë(H Return Value
  1707. °dONLNd¥Z$è+ Result code.
  1708. °dONLNd¡4HBb(>HNote
  1710. °dONLNdΔRZ^q+@This is an asynchronous call that can be made at interrupt time._ΰdONLNdnZz    *WThe CompletionProc is called when the DialString has been stored by ARA.  Since anotherÎY°dONLNd_ÄZå    *`security module could override this DialString by another call to this routine, the user may not°dONLNd¿íZû‘*get called at this DialString.°dONLNdflÆZ∫≈*RThis routine can only be used by a server-side protocol-level code resource (SRPR)
  1711.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú623ˇ⁄dˇ ˇˇˇˇd
  1712. d,     Helvetica
  1713.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1714. °dONLNdRH`ú(\H ARAAllowUser _F_/, Palatino°dONLNd
  1715. pH~m*Syntax,
  1716. Courier
  1718. °dONLNdâgï{+.pascal ARAErr  ARAAllowUser( SecurityReference°dONLNdDâùïÂ(íù MyReference,°dONLNdXî†ò(ù SecurityCompletionProc°dONLNdpîù†˜)èCompletionProc,°dONLNdáü´,(® long°dONLNdëüù´    )èCompletionParam );
  1719. °dONLNd§∫H»à(ƒH Description
  1721. â`°dONLNd∞ÿZ‰    +_This routine is used to let ARA know that the user has been authenticated.  It also informs ARA◊|°dONLNdÍZˆ    *^that the operation has been completed.  ARA will then send the code resource's entry routine a°dONLNdo¸Zw*@kSecurityEnd action, after which ARA proceeds to the next state.
  1722. °dONLNd∞H&Ñ("H
  1723. Parameters
  1725. °dONLNdª6ZB˚+\CompletionProc is a completion routine which will be called when ARA has accepted this call.üí°dONLNdRZ^    *UCompletionParam is additional information you can supply that will be provided to the°dONLNdndZp§*CompletionProc.
  1726. °dONLNd~ÄHéë(äH Return Value
  1728. °dONLNdãûZ™è+ Result code.
  1729. °dONLNdò∫H»b(ƒHNote
  1731. °dONLNdùÿZ‰á+DThis is an asynchronous call that can be made during interrupt time.
  1732. °dONLNd‚ÙHw(˛HSee Also
  1734. °dONLNdÎZ*+&ARADontAllowUser, ARACompleteOperation
  1735.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú624ˇ<dˇ ˇˇˇˇd
  1736. d,     Helvetica
  1737.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1738. °dONLNdRH`∑(\HARADontAllowUser _F_/, Palatino°dONLNdpH~m*Syntax,
  1739. Courier
  1741. °dONLNdâgïì+2pascal ARAErr  ARADontAllowUser( SecurityReference°dONLNdLâ∂ï˛(í∂ MyReference,°dONLNdaî%†C(ù% char°dONLNdkî∂†Ú)ë
  1742. * Message,°dONLNd~ü%´Ø(®% SecurityCompletionProc°dONLNdñü∂´)ëCompletionProc,°dONLNdÆ™%∂C(≥% long°dONLNd∏™∂∂")ëCompletionParam );
  1743. °dONLNdÀ≈H”à(œH Description
  1745. VX°dONLNd◊„ZÔ    +`You can call this routine when the user has failed authentication.  ARA will send a kSecurityEnd°dONLNd8ıZÈ*Zaction to the code resources entry routine, after which ARA will tear down the connection.
  1746. °dONLNdìHÑ(H
  1747. Parameters
  1749. 9˘°dONLNdû/Z;    +^Message is an optional Pascal string which states why the user failed authentication.  You can°dONLNd˝AZMŒ*pass a NIL for the pointer.°dONLNd]Zi÷*TCompletionProc is your routine which will be called when ARA has accepted this call.°dONLNdnyZÖ‰*TCompletionParam is a parameter you can supply which is passed to the CompletionProc.
  1750. °dONLNd√ïH£ë(üH Return Value
  1752. °dONLNd–≥Zøè+ Result code.
  1753. °dONLNd›œH›b(ŸHNote
  1755. °dONLNd‚ÌZ˘á+DThis is an asynchronous call that can be made during interrupt time.
  1756. °dONLNd'    Hw(HSee Also
  1758. °dONLNd0'Z3+"ARAAllowUser, ARACompleteOperation
  1759.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú625ˇ    dˇ ˇˇˇˇd
  1760. d,     Helvetica
  1761.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1762. °dONLNdRH`»(\HARAReadSecurityData _F_/, Palatino°dONLNdpH~m*Syntax,
  1763. Courier
  1765. °dONLNdägñ•+5pascal ARAErr  ARAReadSecurityData( SecurityReference°dONLNdQä∂ñ˛(ì∂ MyReference,°dONLNdfï%°U(û%    void°dONLNdrï∂°Ú)ë
  1766. * DataPtr,°dONLNd܆%¨O(©%    int°dONLNdí†∂¨Ï)ë    DataSize,°dONLNd£´∑í(¥SecurityCompletionProc°dONLNdª´∂∑)®CompletionProc,°dONLNd”∂%¬U(ø%    long°dONLNdfl∂∂¬")ëCompletionParam );
  1767. °dONLNdÚ—Hflà(€H Description
  1769. ∏!°dONLNd˛ÔZ˚    +`This routine is used to read data for the given type of security module which is associated with<c°dONLNd_Z
  1770.     *`either a user or a connection.  On the server this data is associated with a given user.  On theZk°dONLNd¿Z    *`client side this data is associated with the connection.  The maximum amount of data that can be°dONLNd!%Z1≠*stored is 150 bytes.
  1771. °dONLNd6AHOÑ(KH
  1772. Parameters
  1774. °dONLNdA_ZkU+;DataPtr points to where the security data is to be read to.°dONLNd}{ZáΔ*RDataSize is the maximum amount of data to read.  It should not be larger than 150.°dONLNd–óZ£È*ZCompletionProc is a pointer to a routine which will be called when the data has been read.°dONLNd+≥Zø*\CompletionParam is additional information you can provide to be passed to the CompletionProc
  1775. °dONLNdàœH›ë(ŸH Return Value
  1777. °dONLNdïÌZ˘è+ Result code.
  1778. °dONLNd¢    Hb(HNote
  1780. æÿ°dONLNdß'Z3    +^On the ARA server this data is associated with a given user and stored in the users and groups°dONLNd9ZE¶*Ndatabase.  On the client side this data is associated with a given connection.
  1781. °dONLNdUUHcw(_HSee Also
  1783. °dONLNd^sZ∑+DARAReadLockSecurityData, ARAWriteSecurityData, ARAUnlockSecurityData
  1784.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú626ˇ
  1785. Êdˇ ˇˇˇˇd
  1786. d,     Helvetica
  1787.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1788. °dONLNd<HJ‰(FHARAReadLockSecurityData IFI/, Palatino°dONLNdZHhm*Syntax,
  1789. Courier
  1791. °dONLNdtgÄΩ+9pascal ARAErr  ARAReadLockSecurityData( SecurityReference°dONLNdYtŒÄ(}Œ MyReference,°dONLNdn%ã+(à% °dONLNdp>ã\) void°dONLNdy∂ãÚ)x
  1792. * DataPtr,°dONLNdçä%ñU(ì%     int°dONLNdôä∂ñÏ)ë    DataSize,°dONLNd™ï°í(ûSecurityCompletionProc°dONLNd¬ï∂°)®CompletionProc,°dONLNd⁄†%¨7(©%   °dONLNdfi†>¨\) long°dONLNdÁ†∂¨")xCompletionParam );
  1793. °dONLNd˙ªH…à(≈H Description
  1795. Dz°dONLNdŸZ    +YThis routine is used to read and lock data for the given type of security module which is∏‡°dONLNd`ÎZ˜    *bassociated with either a user or a connection.  On the server this data is associated with a given!∏°dONLNd√˝Z        *]user.  On the client side this data is associated with the connection.  The maximum amount ofey°dONLNd!Z    *Zdata that can be read or written is 150 bytes.  You should use the ARAReadLockSecurityDataS∞°dONLNd|!Z-    *ainstead of ARAReadSecurityData if you plan to modify or write the security data.  This is crucial°dONLNdfi3Z?Á*Xon the server, because you can have multiple threads attempting to modify the same data.
  1796. °dONLNd7OH]Ñ(YH
  1797. Parameters
  1799. °dONLNdBmZyU+;DataPtr points to where the security data is to be read to.°dONLNd~âZïΔ*RDataSize is the maximum amount of data to read.  It should not be larger than 150.°dONLNd—•Z±È*ZCompletionProc is a pointer to a routine which will be called when the data has been read.°dONLNd,¡ZÕ*\CompletionParam is additional information you can provide to be passed to the CompletionProc
  1800. °dONLNdâ›HÎë(ÁH Return Value
  1802. °dONLNdñ˚Zè+ Result code.
  1803. °dONLNd£H%b(!HNote
  1805. æÿ°dONLNd®5ZA    +^On the ARA server this data is associated with a given user and stored in the users and groups°dONLNdGZS¶*Ndatabase.  On the client side this data is associated with a given connection.°dONLNdVcZo√*NYou must call ARAUnlockSecurityData to remove the lock from the security data.
  1806. °dONLNd•Hçw(âHSee Also
  1808. °dONLNdÆùZ©°+@ARAReadSecurityData, ARAWriteSecurityData, ARAUnlockSecurityData
  1809.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú627ˇ    bdˇ ˇˇˇˇd
  1810. d,     Helvetica
  1811.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1812. °dONLNdRH`…(\HARAWriteSecurityData _F_/, Palatino°dONLNdpH~m*Syntax,
  1813. Courier
  1815. °dONLNdâgï•+5pascal ARAErr ARAWriteSecurityData( SecurityReference°dONLNdRâ∂ï˛(í∂ MyReference,°dONLNdgî%†U(ù%    void°dONLNdsî∂†Ú)ë
  1816. * DataPtr,°dONLNdÜü%´O(®%    int°dONLNdíü∂´Ï)ë    DataSize,°dONLNd£™∂§(≥   SecurityCompletionProc°dONLNdΩ™∂∂)®CompletionProc,°dONLNd’µ%¡U(æ%    long°dONLNd·µ∂¡")ëCompletionParam );
  1817. °dONLNdÙ–Hfià(⁄H Description
  1819. ∏B°dONLNdÓZ˙    +_This routine can be used by the security modules (mostly configuration code resources) to storeA∂°dONLNd`Z     *cconfiguration data which is associated with either a user or a connection.  On the server this data°dONLNdƒZ∫*Tis associated with a user.  On the client this data is associated with a connection.
  1820. °dONLNd.H<Ñ(8H
  1821. Parameters
  1823. °dONLNd$LZX+(DataPtr points to the data to be stored.°dONLNdMhZt≥*RDataSize is the number of bytes to store.  It should be less than or equal to 150.·Í°dONLNd†ÑZê    *^CompletionProc is a pointer to a completion routine that will be called when the data has been°dONLNdˇñZ¢|*written.°dONLNd≤Zæ*]CompletionParam is additional information you can provide to be passed to the CompletionProc.
  1824. °dONLNdfŒH‹ë(ÿH Return Value
  1826. °dONLNdsÏZ¯è+ Result code.
  1827. °dONLNdÄHb(HNote
  1829. æÿ°dONLNdÖ&Z2    +^On the ARA server this data is associated with a given user and stored in the users and groups°dONLNd‰8ZD¶*Ndatabase.  On the client side this data is associated with a given connection.°dONLNd3TZ`«*RA line-level authentication code resource (CLLN) can not modify the security data.
  1830. °dONLNdÜpH~w(zHSee Also
  1832. °dONLNdèéZöπ+EARAReadSecurityData, ARAReadLockSecurityData, , ARAUnlockSecurityData
  1833.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú628ˇbdˇ ˇˇˇˇd
  1834. d,     Helvetica
  1835.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1836. °dONLNdHHV”(RHARAUnlockSecurityData UFU/, Palatino°dONLNdfHtm*Syntax,
  1837. Courier
  1839. °dONLNdgã´+6pascal ARAErr ARAUnlockSecurityData( SecurityReference°dONLNdT∂ã˛(à∂ MyReference,°dONLNdhäñ§(ì   SecurityCompletionProc°dONLNdÇä∂ñ)®CompletionProc,°dONLNdöï%°a(û%
  1840.       long°dONLNd®ï∂°")ëCompletionParam );
  1841. °dONLNdª∞Hæà(∫H Description
  1843. ”ç°dONLNd«ŒZ⁄    +IThis routine removes a lock from security data that has been locked using°dONLNd‡ZÏÿ*ARAReadLockSecurityData.
  1844. °dONLNd*¸H
  1845. Ñ(H
  1846. Parameters
  1848. ·Í°dONLNd5Z&    +^CompletionProc is a pointer to a completion routine that will be called when the data has been°dONLNdî,Z8|*written.°dONLNdùHZT*]CompletionParam is additional information you can provide to be passed to the CompletionProc.
  1849. °dONLNd˚dHrë(nH Return Value
  1851. °dONLNdÇZéè+ Result code.
  1852. °dONLNdûH¨b(®HNote
  1854. °dONLNdºZ»Á+RYou must call ARAUnlockSecurityData after you have called ARAReadLockSecurityData.
  1855. °dONLNdmÿHÊw(‚HSee Also
  1857. °dONLNdvˆZ≠+BARAReadSecurityData, ARAReadLockSecurityData, ARAWriteSecurityData
  1858.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú629ˇ|dˇ ˇˇˇˇd
  1859. d,     Helvetica
  1860.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1861. °dONLNdRH`¶(\HARAGetUserInfo _F_/, Palatino°dONLNdpH~m*Syntax,
  1862. Courier
  1864. °dONLNdâgïµ+
  1865. pascal ARAErr°dONLNd$âΔïå)_!ARAGetUserInfo( SecurityReference°dONLNdFâùïÂ)◊ MyReference,°dONLNd[î%†=(ù%void°dONLNdcîù†Ÿ)x
  1866. * DataPtr,°dONLNdvü%´7(®%int°dONLNd~üù´”)x    DataSize,°dONLNdê™%∂©(≥%SecurityCompletionProc°dONLNdß™∂∂)ëCompletionProc,°dONLNdøµ%¡=(æ%long°dONLNd«µù¡    )xCompletionParam );
  1867. °dONLNd⁄–Hfià(⁄H Description
  1869. åJ°dONLNdÊÓZ˙    +bThis routine is used to get information about the user.  Currently it returns the user's name.  On°dONLNdIZ ™*Pthe server this is the information for the user dialing in, or being configured.
  1870. °dONLNdöH*Ñ(&H
  1871. Parameters
  1873. °dONLNd•:ZFN+8DataPtr points to where this information will be stored.°dONLNdfiVZbF*3DataSize is the maximum number of bytes to be read.°dONLNdrZ~*^CompletionProc is a completion routine that will be called when the information has been read.°dONLNdqéZö*]CompletionParam is additional information you can provide to be passed to the CompletionProc.
  1874. °dONLNdœ™H∏ë(¥H Return Value
  1876. °dONLNd‹»Z‘è+ Result code.
  1877.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú630ˇÚdˇ ˇˇˇˇd
  1878. d,     Helvetica
  1879.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1880. °dONLNdRH`î(\H ARATickleMe _F_/, Palatino°dONLNd pH~m*Syntax,
  1881. Courier
  1883. °dONLNdägñµ+
  1884. pascal ARAErr°dONLNd!äΔñz)_ARATickleMe( SecurityReference°dONLNdAäùñÂ)◊ MyReference,°dONLNdUï°,(û long°dONLNd_ïù°Ò)èTickleParam );
  1885. °dONLNdn∞Hæà(∫H Description
  1887. %0°dONLNdzŒZ⁄    +^This routine causes ARA to send a  kSecurityTickleAction to the code resource's entry routine.=$°dONLNd⁄‡ZÏ    *YFor example, you can use this routine from completion routines to have your entry routine°dONLNd4ÚZ˛Ä*invoked.
  1888. °dONLNd=HÑ(H
  1889. Parameters
  1891. ^‚°dONLNdH,Z8    +_TickleParam is additional information you can provide which will be passed to the entry routineºÚ°dONLNd®>ZJ    *]in its LongParam parameter.  When ARA calls the entry routine with a kSecurityTickleAction it°dONLNdPZ\≤*Opasses a 0 for the LongParam parameter.  You can use this as a state indicator.
  1892. °dONLNdVlHzë(vH Return Value
  1894. °dONLNdcäZñè+ Result code.
  1895. °dONLNdp¶H¥b(∞HNote
  1897. aY°dONLNduƒZ–    +\This function can be called during interrupt time.  The kSecurityTickleAction is sent to the°dONLNd“÷Z‚*)"MySecurityProcEntry" at SystemTask time.
  1898. °dONLNd¸ÚHw(¸HSee Also
  1900. °dONLNdZº+kSecurityTickleAction
  1901.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú631ˇ,dˇ ˇˇˇˇd
  1902. d,     Helvetica
  1903.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  1904. °dONLNdHHV—(RHARACompleteOperation UFU/, Palatino°dONLNdfHtm*Syntax,
  1905. Courier
  1907. °dONLNdgãµ+
  1908. pascal ARAErr°dONLNd*Δã∂)_(ARACompleteOperation( SecurityReference °dONLNdSŒã"(àŒMyReference );
  1909. °dONLNdböH®à(§H Description
  1911. Vç°dONLNdn∏Zƒ    +]You call this routine when you need to end the operation the code resource is performing.  Itvñ°dONLNdàZ÷    *]causes ARA to send a kSecurityEnd action.  For example the configuration code resource should°dONLNd*‹ZËœ*Wcall this routine when the user has finished inputting information into its dialog box.
  1912. °dONLNdǯHÑ(H
  1913. Parameters
  1915. °dONLNdçZ"º+PMyReference is the unique reference passed to the code resource's entry routine.
  1916. °dONLNdfi2H@ë(<H Return Value
  1918. °dONLNdÎPZ\è+ Result code.
  1919. °dONLNd¯lHzw(vHSee Also
  1921. °dONLNdäZñ+(kSecurityBegin, and kSecurityEnd actions
  1922.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú632ˇfdˇ ˇˇˇˇd
  1923. d,     Helvetica
  1924.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  1925. °dONLNdX6hM(d6+Appendix A:  Security Interface Header File h4h/,
  1926. Courier
  1928. °dONLNd,m6y*P//234567890123456789012345678901234567890123456789012345678901234567890123456789°dONLNd}x6Ñ* M//===========================================================================°dONLNdÀÉ6èB* //°dONLNdŒÉNèl)File:°dONLNd‘É~è)0SecurityInterface.h°dONLNdËé6öB(ó6//°dONLNdÎô6•B* //°dONLNdÓôN•Ê)DThis file is the header file which a third party security vendor can°dONLNd3§6∞B(≠6//°dONLNd6§N∞Ï)Euse to create an add-on security module.  The add-on security modules°dONLNd|Ø6ªB(∏6//°dONLNdØNªÊ)Dcan be used to integrate a security device with Apple Remote Access.°dONLNdƒ∫6ΔB(√6//°dONLNd«≈6—B* //°dONLNd ≈N—L)*Copyright © 1992, 1993 Apple Computer Inc.°dONLNdı–6‹B(Ÿ6//°dONLNd¯–N‹¿)All rights reserved°dONLNd €6ÁB(‰6//°dONLNdÊ6ÚB* //°dONLNdÊNÚ“)Author:  Farzad Sarabi°dONLNd)Ò6˝B(˙6//°dONLNd,¸6B* //°dONLNd/¸NÃ)Modification history:°dONLNdE6B(6//°dONLNdH6B* //°dONLNdKNÑ)    9/29/1993°dONLNdUòº)JFarzad°dONLNd]fi˛)F0Removed declarations for some routines that were°dONLNdé6)B(&6//°dONLNdófi))®    obsolete.°dONLNd°(64B(16//°dONLNd§(N4Ñ)    2/15/1993°dONLNdÆ(ò4º)JFarzad°dONLNd∂(fi4Ï)F-The A5 world and a working environment is now°dONLNd‰36?B(<6//°dONLNdÌ3fi?¯)®/setup for the security modules.  As a result of°dONLNd>6JB(G6//°dONLNd&>fiJÊ)®,this some of the routines in this module are°dONLNdSI6UB(R6//°dONLNd\IfiU)®3obsolete.  Among these are ARAGet/SetMyPrivateData,°dONLNdêT6`B(]6//°dONLNdôTfi`>)®ARAGetMyResFile.°dONLNd™_6kB(h6//°dONLNd≠_NkÑ)    10/6/1992°dONLNd∑_òkº)JFarzad°dONLNdø_fik)FCreated°dONLNd«j6v(s6M//===========================================================================°dONLNdã6ó“*!#ifndef SECURITY_INTERFACE°dONLNd0ñ6¢fi* #define SECURITY_INTERFACE 1°dONLNdM¨6∏ú*#ifndef __FILES__°dONLNd_∑6√f* #include°dONLNdh∑~√¥)H    <Files.h>°dONLNdr¬6ŒZ(À6#endif°dONLNdy„6Ô¿*!#ifndef SECURITY_PUBLIC°dONLNdëÓ6˙f* #include°dONLNdöÓ~˙Í)H"SecurityPublic.h"°dONLNd≠˘6Z(6#endif°dONLNd¥6&*!M//===========================================================================°dONLNd%61B* //°dONLNd%N1r)Macros°dONLNd 06<(96M//===========================================================================°dONLNdZF6R&*(#define kSecurityInterfaceVersion 0x0100°dONLNdÉF>R‡(O>// 0x0100 will be release 1°dONLNdüg6s¢(p6#ifdef __cplusplus°dONLNd≤r6~r*
  1929. extern "C"°dONLNdΩr~~Ñ)H{°dONLNd¬rfi~»)`'// in case we are linking into C++ code°dONLNdÍ}6âZ(Ü6#endif°dONLNdÒ©6µ*,M//===========================================================================°dONLNd?¥6¿B* //°dONLNdB¥N¿l)Types°dONLNdHø6À(»6M//===========================================================================°dONLNdñ’6·h*3// actions are defined in the SecurityPublic.h file
  1930.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú633ˇNdˇ ˇˇˇˇd
  1931. d,     Helvetica
  1932.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  1933. Courier
  1935. °dONLNd66B&(?6(// ARAErr is defined in SecurityPublic.h°dONLNd)A6Mh* 3// SecurityEntryProc is defined in SecurityPublic.h°dONLNd]L6XÜ* 8// SecurityCompletionProc is defined in SecurityPublic.h°dONLNdñb6n*M//===========================================================================°dONLNd‰m6yB* //°dONLNdÁmNyf)Data°dONLNdÏx6Ñ(Å6M//===========================================================================°dONLNd:ô6•*!M//===========================================================================°dONLNdà§6∞B* //°dONLNdã§N∞Ñ)    Functions°dONLNdïØ6ª(∏6M//===========================================================================°dONLNd„≈6—¯*K// the following are functions you can call to have AppleTalk Remote Access°dONLNd/–6‹Ã* // perform these services°dONLNdI¸6Æ*,extern pascal ARAErr°dONLNd^¸Δb)êARARead( SecurityReference°dONLNdz¸ÖÕ)ø MyReference,°dONLNdèˆ(ˆ void°dONLNdôÖ¡)è
  1936. * DataPtr,°dONLNd¨ˆ(ˆ int°dONLNdµÖª)è    DataSize,°dONLNd«ˆ)Ä(&ˆ SecurityCompletionProc°dONLNdflÖ)fl)èCompletionProc,°dONLNd˜(ˆ4(1ˆ long°dONLNd(Ö4Ò)èCompletionParam );°dONLNd36?(<6M//===========================================================================°dONLNdb>6JB* //°dONLNde>NJñ) Description:°dONLNdr>ÆJ‘)`1this routine is used to post an asynchronous read°dONLNd§I6UB(R6//°dONLNd´IÆU⁄)x2operation for data coming from the remote machine.°dONLNdfiT6`B(]6//°dONLNdÂTÆ`)x9This routine can be used by line-level and protocol-level°dONLNd_6kB(h6//°dONLNd&_ÆkŒ)x0authentication modules.  It is not available for°dONLNdXj6vB(s6//°dONLNd_jÆv2)xconfiguration modules.°dONLNdvu6ÅB(~6//°dONLNdyÄ6åB* //°dONLNd|ÄNåê) Parameters:°dONLNdâÄÆå)` MyReference°dONLNdñÄå¬)`this module's unique reference°dONLNdµã6óB(î6//°dONLNdºãÆóÿ)xDataPtr°dONLNdΔãó™)`where to put the read data°dONLNd·ñ6¢B(ü6//°dONLNdËñÆ¢fi)xDataSize°dONLNdÚñ¢‡)`#the maximum number of bytes to read°dONLNd°6≠B(™6//°dONLNd°Æ≠)xCompletionProc°dONLNd,°≠Ê)`$this routine will be called when the°dONLNdQ¨6∏B(µ6//°dONLNd\¨∏§)ÿread request has finished°dONLNdv∑6√B(¿6//°dONLNd}∑Æ√)xCompletionParam°dONLNdç∑√Ú)`&this is information you can provide to°dONLNd¥¬6ŒB(À6//°dONLNdø¬ŒŒ)ÿ be passed to the completion proc°dONLNd‡Õ6ŸB(÷6//°dONLNd„ÿ6‰B* //°dONLNdÊÿN‰ú)
  1937. Return Value:°dONLNdÙÿƉ“)`ARAErr°dONLNd˝ÿ‰¯)`'result code, nonzero indicates an error°dONLNd%„6ÔB(Ï6//°dONLNd(Ó6˙B* //°dONLNd+ÓN˙¢)Creation Date:°dONLNd:ÓÆ˙‰)`    10/6/1992°dONLNdD˘6B(6//°dONLNdG6B* //°dONLNdJN¢)Modifications:°dONLNdY6B(6//°dONLNd\6&* M//===========================================================================°dONLNd™F6RÆ*,extern pascal ARAErr°dONLNdøFΔRh)êARAWrite( SecurityReference°dONLNd›FùRÂ)◊ MyReference,°dONLNdÚQˆ](Zˆ  void°dONLNd˛Qù]Ÿ)ß
  1938. * DataPtr,°dONLNd\ˆh(eˆ  int°dONLNd\ùh”)ß    DataSize,°dONLNd.gˆsÜ(pˆ  SecurityCompletionProc°dONLNdGgùs˜)ßCompletionProc,°dONLNd_rˆ~({ˆ  long°dONLNdkrù~    )ßCompletionParam );°dONLNd~}6â(Ü6M//===========================================================================°dONLNdÃà6îB* //°dONLNdœàNîñ) Description:°dONLNd‹àÆîÊ)`4this routine is used to asynchronously write data to°dONLNdì6üB(ú6//°dONLNdìÆüÏ)x5the remote machine.  It can be used by line-level and°dONLNdNû6™B(ß6//°dONLNdUûÆ™í)x&protocol-level authentication modules.°dONLNd|©6µB(≤6//°dONLNd¥6¿B* //°dONLNdÇ¥N¿ê) Parameters:°dONLNdè¥Æ¿)` MyReference°dONLNdú¥¿å)`your unique reference°dONLNd≤ø6ÀB(»6//°dONLNdπøÆÀÿ)xDataPtr°dONLNd√øÀ™)`the data to be written out°dONLNdfi 6÷B(”6//°dONLNd Æ÷fi)xDataSize°dONLNdÔ ÷∞)`the amount of data to write°dONLNd     ’6·B(fi6//°dONLNd    ’Æ·)xCompletionProc°dONLNd    !’·Ê)`$this routine is called when the data
  1939.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú634ˇdˇ ˇˇˇˇd
  1940. d,     Helvetica
  1941.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  1942. Courier
  1944. °dONLNd66BB(?6//°dONLNd 6BÜ)ÿhas been written out°dONLNd A6MB(J6//°dONLNd'AÆM)xCompletionParam°dONLNd7AM)`)this is extra information you can provide°dONLNdaL6XB(U6//°dONLNdlLX⁄)ÿ"to be passed to the CompletionProc°dONLNdèW6cB(`6//°dONLNdíb6nB* //°dONLNdïbNnú)
  1945. Return Value:°dONLNd£bÆn“)`ARAErr°dONLNd¨bn¯)`'result code, nonzero indicates an error°dONLNd‘m6yB(v6//°dONLNd◊x6ÑB* //°dONLNd⁄xNÑ¢)Creation Date:°dONLNdÈxÆщ)`    10/6/1992°dONLNdÛÉ6èB(å6//°dONLNdˆé6öB* //°dONLNd˘éNö¢)Modifications:°dONLNdô6•B(¢6//°dONLNd §6∞* M//===========================================================================°dONLNdY–6‹t*,5extern pascal ARAErr ARALogMessage( SecurityReference°dONLNdê–ù‹Â(Ÿù MyReference,°dONLNd•€ˆÁ&(‰ˆ    char°dONLNd≤€ùÁŸ)ß
  1946. * Message,°dONLNd≈ʈÚí(Ôˆ    SecurityCompletionProc°dONLNd‡ÊùÚ˜)ßCompletionProc,°dONLNd¯Òˆ˝&(˙ˆ    long°dONLNdÒù˝    )ßCompletionParam );°dONLNd¸6(6M//===========================================================================°dONLNdf6B* //°dONLNdiNñ) Description:°dONLNdvÆÚ)`6you can use this routine to put a message in AppleTalk°dONLNd≠6B(6//°dONLNd¥ÆD)xremote accesses log file.°dONLNdŒ6)B(&6//°dONLNd—(64B* //°dONLNd‘(N4ê) Parameters:°dONLNd·(Æ4)` MyReference°dONLNdÓ(4å)`your unique reference°dONLNd36?B(<6//°dONLNd 3Æ?ÿ)xMessage°dONLNd3?¯)`'a Pascal string which will be logged to°dONLNd=>6JB(G6//°dONLNdH>Jh)ÿin the log file°dONLNdXI6UB(R6//°dONLNd_IÆU)xCompletionProc°dONLNdnIUÊ)`$this routine will be called when the°dONLNdìT6`B(]6//°dONLNdûT`»)ÿlog message has been completed.°dONLNdæ_6kB(h6//°dONLNd≈_Æk)xCompletionParam°dONLNd’_k˛)`(additional information you can supply to°dONLNd˛j6vB(s6//°dONLNd    jv‡)ÿ#be passed on to the completion proc°dONLNd-u6ÅB(~6//°dONLNd0Ä6åB* //°dONLNd3ÄNåú)
  1947. Return Value:°dONLNdAÄÆå“)`ARAErr°dONLNdJÄå¯)`'result code, nonzero indicates an error°dONLNdrã6óB(î6//°dONLNduñ6¢B* //°dONLNdxñN¢¢)Creation Date:°dONLNdáñÆ¢‰)`    10/6/1992°dONLNdë°6≠B(™6//°dONLNdî¨6∏B* //°dONLNdó¨N∏¢)Modifications:°dONLNd¶∑6√B(¿6//°dONLNd©¬6Œ* M//===========================================================================°dONLNd˜Ó6˙t*,5extern pascal ARAErr ARACallBackAt( SecurityReference°dONLNd.Óù˙Â(˜ù MyReference,°dONLNdC˘ˆ&(ˆ    char°dONLNdP˘ùÎ)ß
  1948. * DialString,°dONLNdfˆí(
  1949. ˆ    SecurityCompletionProc°dONLNdÅù˜)ßCompletionProc,°dONLNdôˆ&(ˆ    long°dONLNd¶ù    )ßCompletionParam );°dONLNdπ6&(#6M//===========================================================================°dONLNd%61B* //°dONLNd
  1950. %N1ñ) Description:°dONLNd%Æ1‘)`1this routine can be used during authentication to°dONLNdI06<B(96//°dONLNdP0Æ<»)x/cause the server to call the client back at the°dONLNdÄ;6GB(D6//°dONLNdá;ÆG)xspecified number.°dONLNdôF6RB(O6//°dONLNdúQ6]B* //°dONLNdüQN]ê) Parameters:°dONLNd¨QÆ])` MyReference°dONLNdπQ]å)`your unique reference°dONLNdœ\6hB(e6//°dONLNd÷\ÆhÍ)x
  1951. DialString°dONLNd‚\h⁄)`"this is a pascal string which must°dONLNdg6sB(p6//°dONLNdgsÊ)ÿ$contain a dial string for the number°dONLNd5r6~B({6//°dONLNd@r~™)ÿto call the client back at°dONLNd[}6âB(Ü6//°dONLNdb}Æâ)xCompletionProc°dONLNdq}â
  1952. )`*this proc will be called when the callback°dONLNdúà6îB(ë6//°dONLNdßàîÄ)ÿhas been completed.°dONLNdªì6üB(ú6//°dONLNd¬ìÆü)xCompletionParam°dONLNd“ìüÚ)`&additional information you can provide°dONLNd˘û6™B(ß6//°dONLNdû™)ÿ)that will be passed to the CompletionProc°dONLNd.©6µB(≤6//°dONLNd1¥6¿B* //°dONLNd4¥N¿ú)
  1953. Return Value:°dONLNdB¥Æ¿“)`ARAErr°dONLNdK¥¿¯)`'result code, nonzero indicates an error°dONLNdsø6ÀB(»6//°dONLNdv 6÷B* //°dONLNdy N÷¢)Creation Date:°dONLNdà Æ÷‰)`    10/6/1992°dONLNdí’6·B(fi6//
  1954.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú635ˇ dˇ ˇˇˇˇd
  1955. d,     Helvetica
  1956.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  1957. Courier
  1959. °dONLNd66BB(?6//°dONLNd6NB¢)Modifications:°dONLNdA6MB(J6//°dONLNdL6X* M//===========================================================================°dONLNdcx6Ñt*,5extern pascal ARAErr  ARAAllowUser( SecurityReference°dONLNdöxùÑÂ(Åù MyReference,°dONLNd∞Éèí(åSecurityCompletionProc°dONLNd«Éùè˜)èCompletionProc,°dONLNd‡éö&(ólong°dONLNdÈéùö    )èCompletionParam );°dONLNd¸ô6•(¢6M//===========================================================================°dONLNdJ§6∞B* //°dONLNdM§N∞ñ) Description:°dONLNdZ§Æ∞‡)`3the authentication code on the server can call this°dONLNdéØ6ªB(∏6//°dONLNdïØƪÏ)x5routine to indicate the user has passed this module's°dONLNdÀ∫6ΔB(√6//°dONLNd“∫ÆΔ2)xsecurity requirements.°dONLNdÈ≈6—B(Œ6//°dONLNdÏ–6‹B* //°dONLNdÔ–N‹ê) Parameters:°dONLNd¸–Æ‹)` MyReference°dONLNd    –‹å)`your unique reference°dONLNd€6ÁB(‰6//°dONLNd&€ÆÁ)xCompletionProc°dONLNd5€ÁÏ)`%this routine is called when AppleTalk°dONLNd[Ê6ÚB(Ô6//°dONLNdfÊÚ‡)ÿ#Remote Access has finished handling°dONLNdäÒ6˝B(˙6//°dONLNdïÒ˝Œ)ÿ your authentication information.°dONLNd∂¸6B(6//°dONLNdπ6B* //°dONLNdºNú)
  1960. Return Value:°dONLNd Æ“)`ARAErr°dONLNd”¯)`'result code, nonzero indicates an error°dONLNd˚6B(6//°dONLNd˛6)B* //°dONLNdN)¢)Creation Date:°dONLNdÆ)‰)`    10/6/1992°dONLNd(64B(16//°dONLNd36?B* //°dONLNd 3N?¢)Modifications:°dONLNd/>6JB(G6//°dONLNd2I6U* M//===========================================================================°dONLNdÄu6Åå*,9extern pascal ARAErr  ARADontAllowUser( SecurityReference°dONLNdªu∂Å˛(~∂ MyReference,°dONLNd“Ä%å=(â%char°dONLNd€Ä∂åÚ)ë
  1961. * Message,°dONLNdã%ó©(î%SecurityCompletionProc°dONLNdã∂ó)ëCompletionProc,°dONLNd!ñ%¢=(ü%long°dONLNd*ñ∂¢")ëCompletionParam );°dONLNd=°6≠(™6M//===========================================================================°dONLNdã¨6∏B* //°dONLNdé¨N∏ñ) Description:°dONLNdõ¨Æ∏‡)`3the server security module can call this routine to°dONLNdœ∑6√B(¿6//°dONLNd÷∑Æ√å)x%prevent a user from being allowed in.°dONLNd¸¬6ŒB(À6//°dONLNdˇÕ6ŸB* //°dONLNdÕNŸê) Parameters:°dONLNdÕÆŸ)` MyReference°dONLNdÕŸå)`your unique reference°dONLNd2ÿ6‰B(·6//°dONLNd9ÿƉÿ)xMessage°dONLNdCÿ‰Ê)`$a pascal string stating why the user°dONLNdh„6ÔB(Ï6//°dONLNds„Ôí)ÿwas not allowed access°dONLNdäÓ6˙B(˜6//°dONLNdëÓÆ˙)xCompletionProc°dONLNd†Ó˙Ê)`$this routine will be called when the°dONLNd≈˘6B(6//°dONLNd–˘Ï)ÿ%request for not allowing user has bee°dONLNdˆ6B(
  1962. 6//°dONLNdD)ÿ    processed°dONLNd 6B(6//°dONLNdÆ)xCompletionParam°dONLNd"Ú)`&additional information you can provide°dONLNdI6&B(#6//°dONLNdT&Ú)ÿ&which will be passed to the completion°dONLNd{%61B(.6//°dONLNdÜ%1&)ÿproc°dONLNdã06<B(96//°dONLNdé;6GB* //°dONLNdë;NGú)
  1963. Return Value:°dONLNdü;ÆG“)`ARAErr°dONLNd®;G¯)`'result code, nonzero indicates an error°dONLNd–F6RB(O6//°dONLNd”Q6]B* //°dONLNd÷QN]¢)Creation Date:°dONLNdÂQÆ]‰)`    10/6/1992°dONLNdÔ\6hB(e6//°dONLNdÚg6sB* //°dONLNdıgNs¢)Modifications:°dONLNdr6~B({6//°dONLNd}6â* M//===========================================================================°dONLNdU¥6¿û*7<extern pascal ARAErr  ARAReadSecurityData( SecurityReference°dONLNdí¥∂¿˛(Ω∂ MyReference,°dONLNd©ø%ÀO(»%   void°dONLNdµø∂ÀÚ)ë
  1964. * DataPtr,°dONLNd  %÷I(”%   int°dONLNd’ ∂÷Ï)ë    DataSize,°dONLNdË’·í(fiSecurityCompletionProc°dONLNd’∂·)®CompletionProc,
  1965.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú636ˇ»dˇ ˇˇˇˇd
  1966. d,     Helvetica
  1967.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  1968. Courier
  1970. °dONLNd6%BO(?%   long°dONLNd 6∂B")ëCompletionParam );°dONLNdA6M(J6M//===========================================================================°dONLNdmL6XB* //°dONLNdpLNXñ) Description:°dONLNd}LÆX¯)`7this routine can be used to read data for this security°dONLNdµW6cB(`6//°dONLNdºWÆcÏ)x5module which is associated with either a user (on the°dONLNdÚb6nB(k6//°dONLNd˘bÆn‡)x3server side), or a connection (on the client side).°dONLNd-m6yB(v6//°dONLNd4mÆy¯)x7This routine doesn't lock the data, so use it only when°dONLNdlx6ÑB(Å6//°dONLNdsxÆÑh)xyou just plan to read the data.°dONLNdìÉ6èB(å6//°dONLNdñé6öB* //°dONLNdôéNöê) Parameters:°dONLNd¶éÆö)` MyReference°dONLNd≥éöå)`your unique reference°dONLNd…ô6•B(¢6//°dONLNd–ôÆ•ÿ)xDataPtr°dONLNd⁄ô•¬)`where the data will be read to°dONLNd˘§6∞B(≠6//°dONLNd§Æ∞fi)xDataSize°dONLNd
  1971. §∞»)`maximum number of bytes to read°dONLNd*Ø6ªB(∏6//°dONLNd1Øƪ)xCompletionProc°dONLNd@تÊ)`$this routine will be called when the°dONLNde∫6ΔB(√6//°dONLNdp∫Δ™)ÿread request has completed°dONLNdã≈6—B(Œ6//°dONLNdí≈Æ—)xCompletionParam°dONLNd¢≈—Ú)`&additional information you can provide°dONLNd…–6‹B(Ÿ6//°dONLNd‘–‹‡)ÿ#to be passed to the completion proc°dONLNd¯€6ÁB(‰6//°dONLNd˚Ê6ÚB* //°dONLNd˛ÊNÚú)
  1972. Return Value:°dONLNd ÊÆÚ“)`ARAErr°dONLNdÊÚ¯)`'result code, nonzero indicates an error°dONLNd=Ò6˝B(˙6//°dONLNd@¸6B* //°dONLNdC¸N¢)Creation Date:°dONLNdR¸Æ‰)`    10/6/1992°dONLNd\6B(6//°dONLNd_6B* //°dONLNdbN¢)Modifications:°dONLNdq6)B(&6//°dONLNdt(64* M//===========================================================================°dONLNd¬T6`∞*,?extern pascal ARAErr ARAReadLockSecurityData( SecurityReference°dONLNdT∂`˛(]∂ MyReference,°dONLNd_>kb(h>  void°dONLNd$_∂kÚ)x
  1973. * DataPtr,°dONLNd:j>v\(s>  int°dONLNdCj∂vÏ)x    DataSize,°dONLNdWu%Å©(~%SecurityCompletionProc°dONLNdnu∂Å)ëCompletionProc,°dONLNdâÄ>åb(â>  long°dONLNdìÄ∂å")xCompletionParam );°dONLNd¶ã6ó(î6M//===========================================================================°dONLNdÙñ6¢B* //°dONLNd˜ñN¢ñ) Description:°dONLNdñÆ¢¯)`7this routine can be used to read security data and lock°dONLNd<°6≠B(™6//°dONLNdC°Æ≠)x9it to be modified.  If you are planning on modifying your°dONLNd}¨6∏B(µ6//°dONLNdѨÆ∏Ï)x5data and then writing it, you must call this routine.°dONLNd∫∑6√B(¿6//°dONLNd¡∑Æ√)x9It locks the data until the a ARAUnlockSecurityData call.°dONLNd˚¬6ŒB(À6//°dONLNd˛Õ6ŸB* //°dONLNdÕNŸê) Parameters:°dONLNdÕÆŸ)` MyReference°dONLNdÕŸå)`your unique reference°dONLNd1ÿ6‰B(·6//°dONLNd8ÿƉÿ)xDataPtr°dONLNdBÿ‰∞)`where the data will be read°dONLNd^„6ÔB(Ï6//°dONLNde„ÆÔfi)xDataSize°dONLNdo„Ô‡)`#the maximum number of bytes to read°dONLNdìÓ6˙B(˜6//°dONLNdöÓÆ˙)xCompletionProc°dONLNd©Ó˙Ê)`$this routine will be called when the°dONLNdŒ˘6B(6//°dONLNdŸ˘¬)ÿdata is read into your buffer.°dONLNd¯6B(
  1974. 6//°dONLNdˇÆ)xCompletionParam°dONLNd)`)additional information you can provide to°dONLNd96B(6//°dONLNdD‡)ÿ#be passed on to the CompletionProc.°dONLNdh6&B(#6//°dONLNdk%61B* //°dONLNdn%N1ú)
  1975. Return Value:°dONLNd|%Æ1“)`ARAErr°dONLNdÖ%1¯)`'result code, nonzero indicates an error°dONLNd≠06<B(96//°dONLNd∞;6GB* //°dONLNd≥;NG¢)Creation Date:°dONLNd¬;ÆGÍ)`
  1976. 10/29/1992°dONLNdÕF6RB(O6//°dONLNd–Q6]B* //°dONLNd”QN]¢)Modifications:°dONLNd‚\6hB(e6//°dONLNdÂg6s* M//===========================================================================°dONLNd3û6™Æ*7extern pascal ARAErr°dONLNdHûΔ™∂)ê(ARAUnlockSecurityData( SecurityReference°dONLNdqûŒ™(ߌ MyReference,°dONLNdâ©>µ¬(≤>SecurityCompletionProc°dONLNd†©Œµ()êCompletionProc,°dONLNdª¥>¿h(Ω>   long°dONLNd«¥Œ¿()êCompletionParam°dONLNd◊ø6ÀB(»6);°dONLNd⁄ 6÷* M//===========================================================================°dONLNd    (’6·B* //°dONLNd    +’N·ñ) Description:°dONLNd    8’Æ·()`?if you have read the security data with ARAReadLockSecurityData
  1977.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú637ˇ∫dˇ ˇˇˇˇd
  1978. d,     Helvetica
  1979.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  1980. Courier
  1982. °dONLNd66BB(?6//°dONLNd6ÆB
  1983. )x:you must call this routine to unlock the data.  After this°dONLNdBA6MB(J6//°dONLNdIAÆM∂)x,call others can then lock the security data.°dONLNdvL6XB(U6//°dONLNdyW6cB* //°dONLNd|WNcê) Parameters:°dONLNdâWÆc)` MyReference°dONLNdñWcå)`your unique reference°dONLNd¨b6nB(k6//°dONLNd≥bÆn)xCompletionProc°dONLNd¬bn.)`0this routine is called when the data is unlocked°dONLNdÛm6yB(v6//°dONLNd˙mÆy)xCompletionParam°dONLNd
  1984. my)`+additiona information you can provide to be°dONLNd6x6ÑB(Å6//°dONLNdAxÑ∂)ÿpassed to the CompletionProc°dONLNd^É6èB(å6//°dONLNdaé6öB* //°dONLNddéNöú)
  1985. Return Value:°dONLNdréÆö“)`ARAErr°dONLNd{éö¯)`'result code, nonzero indicates an error°dONLNd£ô6•B(¢6//°dONLNd¶§6∞B* //°dONLNd©§N∞¢)Creation Date:°dONLNd∏§Æ∞Í)`
  1986. 10/29/1992°dONLNd√Ø6ªB(∏6//°dONLNdΔ∫6ΔB* //°dONLNd…∫NΔ¢)Modifications:°dONLNdÿ≈6—B(Œ6//°dONLNd€–6‹* M//===========================================================================°dONLNd)¸6û*,<extern pascal ARAErr ARAWriteSecurityData( SecurityReference°dONLNdf¸∂˛(∂ MyReference,°dONLNd}%O(%   void°dONLNdâ∂Ú)ë
  1987. * DataPtr,°dONLNdû%I(%   int°dONLNd©∂Ï)ë    DataSize,°dONLNdº)(&)   SecurityCompletionProc CompletionProc,°dONLNd(%4O+    long°dONLNd˚(ù4    )xCompletionParam );°dONLNd36?(<6M//===========================================================================°dONLNd\>6JB* //°dONLNd_>NJñ) Description:°dONLNdl>ÆJ¯)`7this routine can be used by the module to write private°dONLNd§I6UB(R6//°dONLNd´IÆU
  1988. )x:data which is either associated with a user (on the server°dONLNdÊT6`B(]6//°dONLNdÌTÆ`∂)x,side), or a connection (on the client side).°dONLNd_6kB(h6//°dONLNdj6vB* //°dONLNd jNvê) Parameters:°dONLNd-jÆv)` MyReference°dONLNd:jvå)`your unique reference°dONLNdPu6ÅB(~6//°dONLNdWuÆÅÿ)xDataPtr°dONLNdauÅ™)`the data to be written out°dONLNd|Ä6åB(â6//°dONLNdÉÄÆåfi)xDataSize°dONLNdçÄå»)`the amount of data to write out°dONLNd≠ã6óB(î6//°dONLNd¥ãÆó)xCompletionProc°dONLNd√ãóÏ)`%this routine is called when AppleTalk°dONLNdÈñ6¢B(ü6//°dONLNdÙñ¢Ï)ÿ%Remote Access has completed the write°dONLNd°6≠B(™6//°dONLNd%°≠D)ÿ    operation°dONLNd/¨6∏B(µ6//°dONLNd6¨Æ∏)xCompletionParam°dONLNdF¨∏Ú)`&additional information you can provide°dONLNdm∑6√B(¿6//°dONLNdx∑√Ú)ÿ&which is passed to the completion proc°dONLNdü¬6ŒB(À6//°dONLNd¢Õ6ŸB* //°dONLNd•ÕNŸú)
  1989. Return Value:°dONLNd≥ÕÆŸ“)`ARAErr°dONLNdºÕŸ¯)`'result code, nonzero indicates an error°dONLNd‰ÿ6‰B(·6//°dONLNdÁ„6ÔB* //°dONLNdÍ„NÔ¢)Creation Date:°dONLNd˘„ÆÔ‰)`    10/6/1992°dONLNdÓ6˙B(˜6//°dONLNd˘6B* //°dONLNd    ˘N¢)Modifications:°dONLNd6B(
  1990. 6//°dONLNd6* M//===========================================================================°dONLNdi;6GÆ*,extern pascal ARAErr°dONLNd~;ΔGå)ê!ARAGetUserInfo( SecurityReference°dONLNd†;ùGÂ)◊ MyReference,°dONLNd∑F%R=(O%void°dONLNdøFùRŸ)x
  1991. * DataPtr,°dONLNd‘Q%]7(Z%int°dONLNd‹Qù]”)x    DataSize,°dONLNdÔ\hí(eSecurityCompletionProc°dONLNd\ùh˜)èCompletionProc,°dONLNd g%s=(p%long°dONLNd(gùs    )xCompletionParam );°dONLNd;r6~({6M//===========================================================================°dONLNdâ}6âB* //°dONLNdå}Nâñ) Description:°dONLNdô}Æâ¯)`7this routine can be called to get information about the°dONLNd—à6îB(ë6//°dONLNdÿàÆî¯)x7the user, such as user name etc.  It is an asynchronous°dONLNdì6üB(ú6//°dONLNdìÆüÃ)xcall.°dONLNdû6™B(ß6//°dONLNd ©6µB* //°dONLNd#©Nµê) Parameters:°dONLNd0©Æµ)` MyReference°dONLNd=©µ™)`your unique code reference°dONLNdX¥6¿B(Ω6//°dONLNd_¥Æ¿ÿ)xDataPtr°dONLNdi¥¿˛)`(pointer to where the user's name (Pascal°dONLNdíø6ÀB(»6//°dONLNdùøÀí)ÿstring) will be stored°dONLNd¥ 6÷B(”6//°dONLNdª Æ÷fi)xDataSize°dONLNd≈ ÷»)`maximum number of bytes to read°dONLNdÂ’6·B(fi6//°dONLNdÏ’Æ·)xCompletionProc°dONLNd˚’·)`)this routine will be called when the call
  1992.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú638ˇdˇ ˇˇˇˇd
  1993. d,     Helvetica
  1994.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  1995. Courier
  1997. °dONLNd66BB(?6//°dONLNd 6B\)ÿ
  1998. has completed°dONLNdA6MB(J6//°dONLNd AÆM)xCompletionParam°dONLNd0AMÚ)`&additional information to be passed to°dONLNdWL6XB(U6//°dONLNdbLXz)ÿthe CompletionProc°dONLNduW6cB(`6//°dONLNdxb6nB* //°dONLNd{bNnú)
  1999. Return Value:°dONLNdâbÆn“)`ARAErr°dONLNdíbn¯)`'result code, nonzero indicates an error°dONLNd∫m6yB(v6//°dONLNdΩx6ÑB* //°dONLNd¿xNÑ¢)Creation Date:°dONLNdœxÆщ)`    10/6/1992°dONLNdŸÉ6èB(å6//°dONLNd‹é6öB* //°dONLNdfléNö¢)Modifications:°dONLNdÓô6•B(¢6//°dONLNdÒ§6∞* M//===========================================================================°dONLNd?€6Á¢*7extern pascal long°dONLNdR€ÆÁå)x%ARAGetMySessionRef( SecurityReference°dONLNdx€ùÁÒ)ÔMyReference );°dONLNdáÊ6Ú(Ô6M//===========================================================================°dONLNd’Ò6˝B* //°dONLNdÿÒN˝ñ) Description:°dONLNdÂÒÆ˝)`9You can call this routine to obtain the session reference°dONLNd¸6B(6//°dONLNd&¸Æ¯)x7for the connection for which your code is loaded.  This°dONLNd^6B(6//°dONLNdeÆ)x9value is unique and stays the same during the connection.°dONLNdü6B(6//°dONLNd¶Æ)x9If you have a security module which has both a line-level°dONLNd‡6)B(&6//°dONLNdÁÆ)Ï)x5and a protocol-level authentication, you can use this°dONLNd(64B(16//°dONLNd$(Æ4Ê)x4unique reference as a key to communicate between the°dONLNdY36?B(<6//°dONLNd`3Æ?)xcode resources.°dONLNdp>6JB(G6//°dONLNdsI6UB* //°dONLNdvINUê) Parameters:°dONLNdÉIÆU)` MyReference°dONLNdêIUÊ)`$this is your code's unique reference°dONLNdµT6`B(]6//°dONLNd∏_6kB* //°dONLNdª_Nkú)
  2000. Return Value:°dONLNd…_ÆkΔ)`long°dONLNd–_k
  2001. )`*the session reference, NULL if there is an°dONLNd˚j6vB(s6//°dONLNdjv,)ÿerror°dONLNd u6ÅB(~6//°dONLNdÄ6åB* //°dONLNdÄNå¢)Creation Date:°dONLNd!ÄÆåÍ)`
  2002. 10/29/1992°dONLNd,ã6óB(î6//°dONLNd/ñ6¢B* //°dONLNd2ñN¢¢)Modifications:°dONLNdA°6≠B(™6//°dONLNdD¨6∏* M//===========================================================================°dONLNdí„6ÔÆ*7extern pascal ARAErr°dONLNdß„ΔÔz)êARATickleMe( SecurityReference°dONLNd«„ùÔÂ)◊ MyReference,°dONLNd›Ó˙,(˜ long°dONLNdÁÓù˙Ò)èTickleParam );°dONLNdˆ˘6(6M//===========================================================================°dONLNdD6B* //°dONLNdGNñ) Description:°dONLNdTÆ˛)`8this routine can be used to have AppleTalk Remote Access°dONLNdç6B(6//°dONLNdîÆÏ)x5call your entry routine with a kSecurityTickleAction.°dONLNd 6&B(#6//°dONLNd—Æ&Ú)x6You can also provide some additional information which°dONLNd%61B(.6//°dONLNd%Æ1h)xis passed to the entry routine.°dONLNd/06<B(96//°dONLNd2;6GB* //°dONLNd5;NGê) Parameters:°dONLNdB;ÆG)` MyReference°dONLNdO;Gå)`your unique reference°dONLNdeF6RB(O6//°dONLNdlFÆR)x TickleParam°dONLNdyFRÚ)`&additional information you can provide°dONLNd†Q6]B(Z6//°dONLNd´Q]‘)ÿ!which is passed to the entry proc°dONLNdÕ\6hB(e6//°dONLNd–g6sB* //°dONLNd”gNsú)
  2003. Return Value:°dONLNd·gÆs“)`ARAErr°dONLNdÍgs¯)`'result code, nonzero indicates an error°dONLNdr6~B({6//°dONLNd}6âB* //°dONLNd}Nâ¢)Creation Date:°dONLNd'}Æâ‰)`    10/6/1992°dONLNd1à6îB(ë6//°dONLNd4ì6üB* //°dONLNd7ìNü¢)Modifications:°dONLNdFû6™B(ß6//°dONLNdI©6µ* M//===========================================================================°dONLNdó’6·§*,=extern pascal ARAErr ARACompleteOperation( SecurityReference °dONLNd’’∂·
  2004. (fi∂MyReference );
  2005.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú639ˇdˇ ˇˇˇˇd
  2006. d,     Helvetica
  2007.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2008. Courier
  2010. °dONLNd66B(?6M//===========================================================================°dONLNdNA6MB* //°dONLNdQANMñ) Description:°dONLNd^AÆMÏ)`5this routine can be called to terminate an operation.°dONLNdîL6XB(U6//°dONLNdõLÆXÊ)x4It causes ARA to send a kSecurityEnd action.  During°dONLNd–W6cB(`6//°dONLNd◊WÆcÊ)x4configuration for example the code resource can call°dONLNd b6nB(k6//°dONLNdbÆn»)x/this routine to indicate that configuration has°dONLNdCm6yB(v6//°dONLNdJmÆyÍ)x
  2011. completed.°dONLNdUx6ÑB(Å6//°dONLNdXÉ6èB* //°dONLNd[ÉNèê) Parameters:°dONLNdhÉÆè)` MyReference°dONLNduÉèå)`your unique reference°dONLNdãé6öB(ó6//°dONLNdéô6•B* //°dONLNdëôN•ú)
  2012. Return Value:°dONLNdüôÆ•“)`ARAErr°dONLNd®ô•¯)`'result code, nonzero indicates an error°dONLNd–§6∞B(≠6//°dONLNd”Ø6ªB* //°dONLNd÷ØNª¢)Creation Date:°dONLNdÂØƪ‰)`    10/6/1992°dONLNdÔ∫6ΔB(√6//°dONLNdÚ≈6—B* //°dONLNdı≈N—¢)Modifications:°dONLNd–6‹B(Ÿ6//°dONLNd€6Á* M//===========================================================================°dONLNdU6¢*,#ifdef __cplusplus°dONLNdh6<* }°dONLNdj6)Z* #endif°dONLNdq>6Jfi*!#endif // SECURITY_INTERFACE
  2013.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú640ˇ≤dˇ ˇˇˇˇd
  2014. d,     Helvetica
  2015.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  2016. °dONLNdN6^(Z6"Appendix B:  Security Module Shell ^4^/,
  2017. Courier
  2019. °dONLNd#c6o*P//234567890123456789012345678901234567890123456789012345678901234567890123456789°dONLNdtn6z* M//===========================================================================°dONLNd¬y6ÖB* //°dONLNd≈yNÖl)File:°dONLNdÀy~Öÿ)0SecurityShell.c°dONLNd€Ñ6êB(ç6//°dONLNdfiè6õB* //°dONLNd·èNõŒ)@This file contains a shell for add-on security modules for Apple°dONLNd"ö6¶B(£6//°dONLNd%öN¶¬)>Remote Access.  This code can be duplicated to write an add-on°dONLNdd•6±B(Æ6//°dONLNdg•N±Ã)security code module.°dONLNd}∞6ºB(π6//°dONLNdĪ6«B* //°dONLNdɪN«L)*Copyright © 1992, 1993 Apple Computer Inc.°dONLNdÆΔ6“B(œ6//°dONLNd±ΔN“¿)All rights reserved°dONLNd≈—6›B(⁄6//°dONLNd»‹6ËB* //°dONLNdÀ‹NË“)Author:  Farzad Sarabi°dONLNd‚Á6ÛB(6//°dONLNdÂÚ6˛B* //°dONLNdËÚN˛Ã)Modification history:°dONLNd˛˝6    B(6//°dONLNd6B* //°dONLNdNÑ)    5/10/1993°dONLNdòº)JFarzad°dONLNdfi)F1A little cleanup, and added a completion routine.°dONLNdH6B(6//°dONLNdQfiJ)®Some more comments°dONLNdd6*B('6//°dONLNdgN*Ñ)    10/6/1992°dONLNdqò*º)JFarzad°dONLNdyfi*)FCreated°dONLNdÅ)65(26M//===========================================================================°dONLNdœU6af*,#include°dONLNdÿU~a¸)H"SecurityInterface.h"°dONLNdÓv6Ç(6&// #define SecurityShellVersion 0x0100°dONLNdó6£*!M//===========================================================================°dONLNdc¢6ÆB* //°dONLNdf¢NÆΔ)Example of Your Code°dONLNd{≠6π(∂6M//===========================================================================°dONLNd…√6œ∫*// function prototypes°dONLNd‡Œ6⁄x* static long°dONLNdÌŒò⁄L)bDoMyStartup( SecurityReference°dONLNd ŒU⁄ù)Ω MyReference,°dONLNd Ÿfi¸(‚fi long°dONLNd)ŸUÂù)w LongParam );°dONLNd6‰6x(Ì6 static long°dONLNdC‰òR)bDoMyShutdown( SecurityReference°dONLNdd‰ÖÕ)Ì MyReference,°dONLNdxÔfi˚(¯fi  long°dONLNdÉÔn˚∂)ê LongParam );°dONLNdê˙6x(6 static long°dONLNdù˙ò@)bDoMyBegin( SecurityReference°dONLNd∫˙Uù)Ω MyReference,°dONLNdÕΔ(Δ   long°dONLNdŸUù)è LongParam );°dONLNdÊ6x(6 static long°dONLNdÛò4)bDoMyEnd( SecurityReference°dONLNd>Ü)¶ MyReference,°dONLNd!Δ'‰($Δ long°dONLNd*>'Ü)x LongParam );°dONLNd7&62x(/6 static long°dONLNdD&ò2d)b"DoMyDataHandler( SecurityReference°dONLNdg&n2∂)÷ MyReference,°dONLNd|1ˆ=(:ˆ long°dONLNdÖ1n=∂)x LongParam );°dONLNdí<6Hx(E6 static long°dONLNdü<òHj)b#DoMyAbortHandler( SecurityReference°dONLNdƒ<ùHÂ(Eù MyReference,°dONLNdŸGˆS(Pˆ  long°dONLNd‰GÖSÕ)è LongParam );°dONLNdÒR6^x([6 static long°dONLNd˛Rò^p)b$DoMyTickleHandler( SecurityReference°dONLNd#RÖ^Õ)Ì MyReference,°dONLNd8]ˆi (fˆ   long°dONLNdD]ÖiÕ)è LongParam );°dONLNdQh6tx(q6 pascal void°dONLNd^hòtj)b#MyCompletionProc( SecurityReference°dONLNdÉhùtÂ(qù MyReference,°dONLNdòsˆ(|ˆ  int°dONLNd¢sÖ«)è ResultCode,°dONLNd∂~ˆä(ሠ void°dONLNd¡~Öä¡)è
  2020. * DataPtr,°dONLNd‘âˆï(툠 int°dONLNdfiâÖïª)è    DataSize,°dONLNd(ùˆ  long°dONLNd˚îÖ†Ò)èCompletionParam );°dONLNdÀ6◊¯(‘6K// the following is a shell for your code.  It shows how your entry routine°dONLNdZ÷6‚‡* G// should be structured.  Empty supporting routines for the actions are
  2021.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú641ˇ$dˇ ˇˇˇˇd
  2022. d,     Helvetica
  2023.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2024. Courier
  2026. °dONLNd66B~(?6 // provided.°dONLNd
  2027. W6cx*! // WARNING:°dONLNdb6nB* //°dONLNdbgn·)1?Don't change the name of this routine.  We may change it in the°dONLNd]m6yB(v6//°dONLNdamgyô)13future.  This is the routine ARA expects and calls.°dONLNdïÉ6èx(å6 pascal long°dONLNd¢Éòèp)b$MySecurityProcEntry( SecurityActions°dONLNd»Éùè«(åùAction,°dONLNdŸéöz(ó SecurityReference°dONLNdÌéùöÂ)è MyReference,°dONLNdô•,(¢ long°dONLNd
  2028. ôù•fl)è LongParam )°dONLNd§6∞(≠6M//===========================================================================°dONLNdgØ6ªB* //°dONLNdjØNªñ) Description:°dONLNdwØƪ¯)`7this is the entry point for the ??? security operation.°dONLNdØ∫6ΔB(√6//°dONLNd∂∫ÆΔÊ)x4It is called by AppleTalk Remote Access to have this°dONLNdÎ≈6—B(Œ6//°dONLNdÚ≈Æ—Œ)x0security module perform the given operation.  It°dONLNd#–6‹B(Ÿ6//°dONLNd*–Æ‹Œ)x0dispatches to a variety of routines based on the°dONLNd[€6ÁB(‰6//°dONLNdb€ÆÁ)xrequested action.°dONLNdtÊ6ÚB(Ô6//°dONLNdwÒ6˝B* //°dONLNdzÒN˝ê) Parameters:°dONLNdáÒÆ˝“)`Action°dONLNdëÒ%˝¡)wthe action to be performed°dONLNd¨¸6B(6//°dONLNd≥¸Æ)x MyReference°dONLNd¡¸%˜)w#this is a unique value representing°dONLNdÂ6B(6//°dONLNdÒ%Ò)Ô"this instance of this code module.°dONLNd6B(6//°dONLNdÆÿ)xDataPtr°dONLNd&%µ)wthe data for this action°dONLNd?6)B(&6//°dONLNdFÆ)fi)xDataSize°dONLNdQ%)Ö)wthe size of data°dONLNdb(64B(16//°dONLNde36?B* //°dONLNdh3N?ú)
  2029. Return Value:°dONLNdv3Æ?Δ)`long°dONLNd~3%?Î)w!result code, nonzero indicates an°dONLNd†>6JB(G6//°dONLNd¨>%Jfl)Ôerror.  Its value is one of the°dONLNdÃI6UB(R6//°dONLNdÿI%Uù)ÔSecurityResultCodes.°dONLNdÌT6`B(]6//°dONLNd_6kB* //°dONLNdÛ_Nk¢)Creation Date:°dONLNdj6vB(s6//°dONLNdu6ÅB* //°dONLNduNÅ¢)Modifications:°dONLNdÄ6åB(â6//°dONLNdã6ó* M//===========================================================================°dONLNdhñ6¢<* {°dONLNdk°N≠¥+ switch ( Action )°dONLNd}°Δ≠Ã)x{°dONLNdÄ∑N√r(¿N  case°dONLNdá∑~√‰)0kSecurityStartup:°dONLNdõ¬gŒu(Àg-return DoMyStartup( MyReference, LongParam );°dONLNd „NÔr(ÏN  case°dONLNd—„~ÔÍ)0kSecurityShutdown:°dONLNdÂÓN˙Z(˜N  °dONLNdËÓg˙{).return DoMyShutdown( MyReference, LongParam );°dONLNdNr(N  case°dONLNd~ÿ)0kSecurityBegin:°dONLNd0N&Z(#N  °dONLNd3g&i)+return DoMyBegin( MyReference, LongParam );°dONLNd`;NGr(DN  case°dONLNdg;~GÃ)0
  2030. kSecurityEnd:°dONLNdvFNRZ(ON  °dONLNdyFgR]))return DoMyEnd( MyReference, LongParam );°dONLNd§gNsr(pN  case°dONLNd´g~s)0kSecurityDataAvailable:°dONLNd≈rg~ç({g1return DoMyDataHandler( MyReference, LongParam );°dONLNd¯ìNür(úN  case°dONLNdˇì~üÿ)0kSecurityAbort:°dONLNdûg™ì(ßg2return DoMyAbortHandler( MyReference, LongParam );°dONLNdEøNÀr(»N  case°dONLNdLø~À)0kSecurityTickleAction:°dONLNdd N÷Z(”N  °dONLNdg g÷ô)3return DoMyTickleHandler( MyReference, LongParam );
  2031.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú642ˇdˇ ˇˇˇˇd
  2032. d,     Helvetica
  2033.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2034. Courier
  2036. °dONLNd6NBT(?N}°dONLNdLNX2*&return ( kSecurityUnsupportedAction );°dONLNd*W6c<(`6}°dONLNd,é6öx*7 static long°dONLNd9éòöL)bDoMyStartup( SecurityReference°dONLNdXéUöù)Ω MyReference,°dONLNdlôfi•¸(¢fi long°dONLNduôU•ó)w LongParam )°dONLNdŧ6∞(≠6M//===========================================================================°dONLNdœØ6ªB* //°dONLNd“ØNªñ) Description:°dONLNdflØƪÚ)`6this routine handles the kSecurityStartup action.  You°dONLNd∫6ΔB(√6//°dONLNd∫ÆΔŒ)x0should allocate any memory and setup the working°dONLNdN≈6—B(Œ6//°dONLNdU≈Æ—t)x!environment (e.g. A5 world) here.°dONLNdw–6‹B(Ÿ6//°dONLNdz€6ÁB* //°dONLNd}€NÁê) Parameters:°dONLNdä€ÆÁ)` MyReference°dONLNdó€ÁÄ)`My unique reference°dONLNd´Ê6ÚB(Ô6//°dONLNd≤ÊÆÚ‰)x    LongParam°dONLNdΩÊÚí)`additional information°dONLNd‘Ò6˝B(˙6//°dONLNd◊¸6B* //°dONLNd⁄¸Nú)
  2037. Return Value:°dONLNd˸ÆΔ)`long°dONLNdÔ¸Ê)`$result code, nonzero indicates error°dONLNd6B(6//°dONLNd6B* //°dONLNdN¢)Creation Date:°dONLNd)6)B(&6//°dONLNd,(64B* //°dONLNd/(N4¢)Modifications:°dONLNd>36?B(<6//°dONLNdA>6J* M//===========================================================================°dONLNdèI6U<* {°dONLNdëT6`ÿ* #pragma unused(MyReference)°dONLNd≠_6kÃ* #pragma unused(LongParam)°dONLNd»uNÅÊ+D// this routine is called when the module has just been loaded.  You°dONLNdÄNåÏ* E// can preallocate any memory you need.  You are not yet starting any°dONLNdUãNóÜ* 4// to do what this code resource is responsible for.°dONLNdã°N≠ò*7// You can allocate and release memory in this routine.°dONLNdƒ∑N√Í*return ( kSecurityNoErr );°dONLNdfl¬6Œ<(À6}°dONLNd·Ó6˙x*, static long°dONLNdÓÓò˙R)bDoMyShutdown( SecurityReference°dONLNdÓÖ˙Õ)Ì MyReference,°dONLNd#˘fi(fi  long°dONLNd.˘n∞)ê LongParam )°dONLNd:6(
  2038. 6M//===========================================================================°dONLNdà6B* //°dONLNdãNñ) Description:°dONLNdòƯ)`7this routine handles the kSecurityShutdown action.  You°dONLNd–6&B(#6//°dONLNd◊Æ&Ú)x6should release any memory allocated by the DoMyStartup°dONLNd%61B(.6//°dONLNd%Æ1fi)xroutine.°dONLNd06<B(96//°dONLNd!;6GB* //°dONLNd$;NGê) Parameters:°dONLNd1;ÆG)` MyReference°dONLNd>;GÄ)`My unique reference°dONLNdRF6RB(O6//°dONLNdYFÆR‰)x    LongParam°dONLNddFRí)`additional information°dONLNd{Q6]B(Z6//°dONLNd~\6hB* //°dONLNdÅ\Nhú)
  2039. Return Value:°dONLNdè\ÆhΔ)`long°dONLNdñ\hÊ)`$result code, nonzero indicates error°dONLNdªg6sB(p6//°dONLNdær6~B* //°dONLNd¡rN~¢)Creation Date:°dONLNd–}6âB(Ü6//°dONLNd”à6îB* //°dONLNd÷àNî¢)Modifications:°dONLNdÂì6üB(ú6//°dONLNdËû6™* M//===========================================================================°dONLNd6©6µ<* {°dONLNd8¥6¿ÿ* #pragma unused(MyReference)°dONLNdTø6ÀÃ* #pragma unused(LongParam)°dONLNdo’N·Ê+D// this is the last routine that is called before your code resource
  2040.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú643ˇ⁄dˇ ˇˇˇˇd
  2041. d,     Helvetica
  2042.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2043. Courier
  2045. °dONLNd6NB¯(?NG// is released.  Just do any cleanup you need to perform.  ARA services°dONLNdIANM* // are no longer available.°dONLNdfWNcò*7// You can allocate and release memory in this routine.°dONLNdümNyÍ*return ( kSecurityNoErr );°dONLNd∫x6Ñ<(Å6}°dONLNdº§6∞x*, static long°dONLNd…§ò∞@)bDoMyBegin( SecurityReference°dONLNdʧU∞ù)Ω MyReference,°dONLNd˘ØΔª(∏Δ   long°dONLNdØUªó)è LongParam )°dONLNd∫6Δ(√6M//===========================================================================°dONLNd_≈6—B* //°dONLNdb≈N—ñ) Description:°dONLNdo≈Æ—Ï)`5this routine handles the kSecurityBeing action.  This°dONLNd•–6‹B(Ÿ6//°dONLNd¨–Æ‹Ï)x5routine should start the operations the code resource°dONLNd‚€6ÁB(‰6//°dONLNdÈ€ÆÁÏ)x5must do.  For example an authentication code resource°dONLNdÊ6ÚB(Ô6//°dONLNd&ÊÆÚû)x(should start the authentication process.°dONLNdOÒ6˝B(˙6//°dONLNdR¸6B* //°dONLNdU¸Nê) Parameters:°dONLNdb¸Æ)` MyReference°dONLNdo¸Ä)`My unique reference°dONLNdÉ6B(6//°dONLNdäƉ)x    LongParam°dONLNdïí)`additional information°dONLNd¨6B(6//°dONLNdØ6)B* //°dONLNd≤N)ú)
  2046. Return Value:°dONLNd¿Æ)Δ)`long°dONLNd«)Ê)`$result code, nonzero indicates error°dONLNdÏ(64B(16//°dONLNdÔ36?B* //°dONLNdÚ3N?¢)Creation Date:°dONLNd>6JB(G6//°dONLNdI6UB* //°dONLNdINU¢)Modifications:°dONLNdT6`B(]6//°dONLNd_6k* M//===========================================================================°dONLNdgj6v<* {°dONLNdiu6Åÿ* #pragma unused(MyReference)°dONLNdÖÄ6åÃ* #pragma unused(LongParam)°dONLNd†ñN¢‡+C// This routine is called to actually start the code resource to do°dONLNd°N≠‡* C// what it's responsible for.  E.g. an authentication code resource°dONLNd*¨N∏‡* C// should start the authentication process.  A configuration module°dONLNdo∑N√,* %// can start displaying a dialog etc.°dONLNdñÕNŸò*7// You can allocate and release memory in this routine.°dONLNdœ„NÔÍ*return ( kSecurityNoErr );°dONLNdÍÓ6˙<(˜6}°dONLNdÏ6&x*, static long°dONLNd˘ò&4)bDoMyEnd( SecurityReference°dONLNd>&Ü)¶ MyReference,°dONLNd'%Δ1‰(.Δ long°dONLNd0%>1Ä)x LongParam )°dONLNd<06<(96M//===========================================================================°dONLNdä;6GB* //°dONLNdç;NGñ) Description:°dONLNdö;ÆG)`9this routine handles the kSecurityEnd action.  The action°dONLNd‘F6RB(O6//°dONLNd€FÆR‡)x3is sent to signal the end of the operation the code°dONLNdQ6]B(Z6//°dONLNdQÆ]P)xresource was created to do.°dONLNd2\6hB(e6//°dONLNd5g6sB* //°dONLNd8gNsê) Parameters:°dONLNdEgÆs)` MyReference°dONLNdRgsÄ)`My unique reference°dONLNdfr6~B({6//°dONLNdmrÆ~‰)x    LongParam°dONLNdxr~í)`additional information°dONLNdè}6âB(Ü6//°dONLNdíà6îB* //°dONLNdïàNîú)
  2047. Return Value:°dONLNd£àÆîΔ)`long°dONLNd™àîÊ)`$result code, nonzero indicates error°dONLNdœì6üB(ú6//°dONLNd“û6™B* //°dONLNd’ûN™¢)Creation Date:°dONLNd‰©6µB(≤6//°dONLNdÁ¥6¿B* //°dONLNdÍ¥N¿¢)Modifications:°dONLNd˘ø6ÀB(»6//°dONLNd¸ 6÷* M//===========================================================================°dONLNdJ’6·<* {
  2048.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú644ˇ¯dˇ ˇˇˇˇd
  2049. d,     Helvetica
  2050.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2051. Courier
  2053. °dONLNd66Bÿ(?6#pragma unused(MyReference)°dONLNdA6MÃ* #pragma unused(LongParam)°dONLNd7WNcÊ+D// This routine is called when the code resource is finished.  It is°dONLNd}bNnÊ* D// called as a result of you calling ARAAllowUser, ARADontAllowUser,°dONLNd√mNyŒ* @// ARACompleteOperation, or after ARA aborts your code resource.°dONLNdxNÑÊ* D// You could for example cleanup any outstanding asynch calls to the°dONLNdKÉNèt* 1// Mac OS.  ARA services are no longer available.°dONLNd~ôN•ò*7// You can allocate and release memory in this routine.°dONLNd∑ØNªÍ*return ( kSecurityNoErr );°dONLNd“∫6Δ<(√6}°dONLNd‘Ê6Úx*, static long°dONLNd·ÊòÚd)b"DoMyDataHandler( SecurityReference°dONLNdÊnÚ∂)÷ MyReference,°dONLNdÒˆ˝(˙ˆ long°dONLNd"Òn˝∞)x LongParam )°dONLNd.¸6(6M//===========================================================================°dONLNd|6B* //°dONLNdNñ) Description:°dONLNdåƯ)`7this routine handles the kSecurityDataAvailable action.°dONLNdƒ6B(6//°dONLNdÀÆÏ)x5The action is sent when data has arrived for the code°dONLNd6)B(&6//°dONLNdÆ)‰)x    resource.°dONLNd(64B(16//°dONLNd36?B* //°dONLNd3N?ê) Parameters:°dONLNd%3Æ?)` MyReference°dONLNd23?Ä)`My unique reference°dONLNdF>6JB(G6//°dONLNdM>ÆJ‰)x    LongParam°dONLNdX>Jí)`additional information°dONLNdoI6UB(R6//°dONLNdrT6`B* //°dONLNduTN`ú)
  2054. Return Value:°dONLNdÉTÆ`Δ)`long°dONLNdäT`Ê)`$result code, nonzero indicates error°dONLNdØ_6kB(h6//°dONLNd≤j6vB* //°dONLNdµjNv¢)Creation Date:°dONLNdƒu6ÅB(~6//°dONLNd«Ä6åB* //°dONLNd ÄNå¢)Modifications:°dONLNdŸã6óB(î6//°dONLNd‹ñ6¢* M//===========================================================================°dONLNd*°6≠<* {°dONLNd,¨6∏ÿ* #pragma unused(MyReference)°dONLNdH∑6√Ã* #pragma unused(LongParam)°dONLNdcÕNŸ¯+G// This routine is not used in this release of the ARA Add-on Security.°dONLNd¨ÿN‰Ú* F// In future releases we may use this to indicate data being available°dONLNdÙ„NÔ‡* C// for you.  ARA may in the future send events to a modeless dialog°dONLNd9ÓN˙8* '// box using the DataAvailable message.°dONLNdbNò*7// You can allocate and release memory in this routine.°dONLNdõN&Í*return ( kSecurityNoErr );°dONLNd∂%61<(.6}°dONLNd∏Q6]x*, static long°dONLNd≈Qò]j)b#DoMyAbortHandler( SecurityReference°dONLNdÍQù]Â(Zù MyReference,°dONLNdˇ\ˆh(eˆ  long°dONLNd
  2055. \Öh«)è LongParam )°dONLNdg6s(p6M//===========================================================================°dONLNddr6~B* //°dONLNdgrN~ñ) Description:°dONLNdtrÆ~Ê)`4this routine handles the kSecurityAbort action.  The°dONLNd©}6âB(Ü6//°dONLNd∞}ÆâÚ)x6abort action is sent when the code resources operation°dONLNdÁà6îB(ë6//°dONLNdÓàÆîz)x"needs to be terminated abnormally.°dONLNdì6üB(ú6//°dONLNdû6™B* //°dONLNdûN™ê) Parameters:°dONLNd$ûÆ™)` MyReference°dONLNd1û™Ä)`My unique reference°dONLNdE©6µB(≤6//°dONLNdL©Æµ‰)x    LongParam°dONLNdW©µí)`additional information°dONLNdn¥6¿B(Ω6//°dONLNdqø6ÀB* //°dONLNdtøNÀú)
  2056. Return Value:°dONLNdÇøÆÀΔ)`long°dONLNdâøÀÊ)`$result code, nonzero indicates error°dONLNdÆ 6÷B(”6//°dONLNd±’6·B* //°dONLNd¥’N·¢)Creation Date:
  2057.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú645ˇ‹dˇ ˇˇˇˇd
  2058. d,     Helvetica
  2059.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2060. Courier
  2062. °dONLNd66BB(?6//°dONLNdA6MB* //°dONLNdANM¢)Modifications:°dONLNdL6XB(U6//°dONLNdW6c* M//===========================================================================°dONLNdfb6n<* {°dONLNdhm6y‘* E// you can remove the unused pragma for any of the parameters you use°dONLNdÆx6Ñÿ* #pragma unused(MyReference)°dONLNd É6èÃ* #pragma unused(LongParam)°dONLNdÂôN•⁄+B// This routine is called when the code resource is being aborted.°dONLNd)§N∞Ï* E// You should not make any more calls to ARA services, and you should°dONLNdpØNª‡* C// start your abort process.  You will receive the End and Shutdown°dONLNdµ∫NΔ*  // actions a little while later.°dONLNd◊–N‹ò*7// You can allocate and release memory in this routine.°dONLNdÊNÚÍ*return ( kSecurityNoErr );°dONLNd+Ò6˝<(˙6}°dONLNd-6)x*, static long°dONLNd:ò)p)b$DoMyTickleHandler( SecurityReference°dONLNd_Ö)Õ)Ì MyReference,°dONLNdt(ˆ4 (1ˆ   long°dONLNdÄ(Ö4«)è LongParam )°dONLNdå36?(<6M//===========================================================================°dONLNd⁄>6JB* //°dONLNd›>NJñ) Description:°dONLNdÍ>ÆJÏ)`5this routine handles the kSecurityTickle action.  ARA°dONLNd I6UB(R6//°dONLNd'IÆU‡)x3sends this action periodically.  The action is also°dONLNd[T6`B(]6//°dONLNdbTÆ`¯)x7generated as a result of a call to ARATickleMe routine.°dONLNdö_6kB(h6//°dONLNd¢j6vB* //°dONLNd•u6ÅB* //°dONLNd®uNÅê) Parameters:°dONLNdµuÆÅ)` MyReference°dONLNd¬uÅÄ)`My unique reference°dONLNd÷Ä6åB(â6//°dONLNd›ÄÆå‰)x    LongParam°dONLNdËÄåÊ)`$When ARA calls this value will be 0,°dONLNd
  2063. ã6óB(î6//°dONLNdãó‡)ÿ#otherwise it is the value passed to°dONLNd<ñ6¢B(ü6//°dONLNdGñ¢û)ÿthe ARATickleMe routine.°dONLNd`°6≠B(™6//°dONLNdc¨6∏B* //°dONLNdf¨N∏ú)
  2064. Return Value:°dONLNdt¨Æ∏Δ)`long°dONLNd{¨∏Ê)`$result code, nonzero indicates error°dONLNd†∑6√B(¿6//°dONLNd£¬6ŒB* //°dONLNd¶¬NŒ¢)Creation Date:°dONLNdµÕ6ŸB(÷6//°dONLNd∏ÿ6‰B* //°dONLNdªÿN‰¢)Modifications:°dONLNd „6ÔB(Ï6//°dONLNdÕÓ6˙* M//===========================================================================°dONLNd˘6<* {°dONLNd6‘* E// you can remove the unused pragma for any of the parameters you use°dONLNdc6ÿ* #pragma unused(MyReference)°dONLNd6&Ã* #pragma unused(LongParam)°dONLNdö0N<Ï+E// ARA calls this routine periodically.  You can also initiate a call°dONLNd·;NG»* ?// to this routine by calling ARATickleMe.  When ARA calls this°dONLNd"FNRÚ* F// routine the LongParam value will be 0 (zero).  When it is called as°dONLNdjQN]Ú* F// a result of a call to ARATickleMe the LongParam will have the value°dONLNd≤\Nh¸* // you passed to ARATickleMe.°dONLNd—rN~ò*7// You can allocate and release memory in this routine.°dONLNd
  2065. àNîÍ*return ( kSecurityNoErr );°dONLNd%ì6ü<(ú6}°dONLNd'ø6Àx*, pascal void°dONLNd4øòÀj)b#MyCompletionProc( SecurityReference°dONLNdYøùÀÂ(»ù MyReference,°dONLNdn ˆ÷(”ˆ  int°dONLNdx Ö÷«)è ResultCode,°dONLNdå’ˆ·(fiˆ  void°dONLNdó’Ö·¡)è
  2066. * DataPtr,
  2067.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú646ˇ
  2068. dˇ ˇˇˇˇd
  2069. d,     Helvetica
  2070.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0,
  2071. Courier
  2073. °dONLNd6ˆB(?ˆ  int°dONLNd
  2074. 6ÖBª)è    DataSize,°dONLNdAˆM(Jˆ  long°dONLNd'AÖMÎ)èCompletionParam )°dONLNd9L6X(U6M//===========================================================================°dONLNdáW6cB* //°dONLNdäWNcñ) Description:°dONLNdóWÆc¯)`7this is an example of your a completion routine you can°dONLNdœb6nB(k6//°dONLNd÷bÆnÚ)x6use for calls to asynch ARA services.  You can use one°dONLNd
  2075. m6yB(v6//°dONLNdmÆy˛)x8completion proc and distinguish the reason it was called°dONLNdMx6ÑB(Å6//°dONLNdTxÆÑ∞)x+by the value passed in the CompletionParam.°dONLNdÄÉ6èB(å6//°dONLNdàé6öB* //°dONLNdãô6•B* //°dONLNdéôN•ê) Parameters:°dONLNdõôÆ•)` MyReference°dONLNd®ô•å)`your unique reference°dONLNdæ§6∞B(≠6//°dONLNd≈§Æ∞Í)x
  2076. ResultCode°dONLNd—§∞Ú)`&result of the asynch ARA call you made°dONLNd¯Ø6ªB(∏6//°dONLNdˇØƪÿ)xDataPtr°dONLNd    ØªÏ)`%pointer to the data passed to the ARA°dONLNd/∫6ΔB(√6//°dONLNd:∫Δ&)ÿproc°dONLNd?≈6—B(Œ6//°dONLNdF≈Æ—fi)xDataSize°dONLNdP≈—ò)`actual size of the data°dONLNdh–6‹B(Ÿ6//°dONLNdo–Æ‹)xCompletionParam°dONLNd–‹‡)`#additional information you provided°dONLNd§€6ÁB(‰6//°dONLNdØ€Áò)ÿto the ARA service proc°dONLNd«Ê6ÚB(Ô6//°dONLNd Ò6˝B* //°dONLNdÕÒN˝ú)
  2077. Return Value:°dONLNd€ÒÆ˝Δ)`none°dONLNd‡¸6B(6//°dONLNd„6B* //°dONLNdÊN¢)Creation Date:°dONLNdı6B(6//°dONLNd¯6)B* //°dONLNd˚N)¢)Modifications:°dONLNd
  2078. (64B(16//°dONLNd
  2079. 36?* M//===========================================================================°dONLNd[>6J<* {°dONLNd]I6U‘* E// you can remove the unused pragma for any of the parameters you use°dONLNd£T6`ÿ* #pragma unused(MyReference)°dONLNdø_6k“* #pragma unused(ResultCode)°dONLNd⁄j6v¿* #pragma unused(DataPtr)°dONLNdÚu6ÅΔ* #pragma unused(DataSize)°dONLNd Ä6å* #pragma unused(CompletionParam)°dONLNd,ñN¢ê+ // WARNING:°dONLNd9°N≠Z* //°dONLNd>°ò≠Ë)J8Do not attempt to allocate or release any memory in this°dONLNdx¨N∏Z(µN//°dONLNd}¨ò∏‹)J6routine.  Also don't call any Mac Toolbaox/OS routines°dONLNd∂∑N√Z(¿N//°dONLNdª∑ò√Ó)J9that allocate or release memory.  If you need to do this,°dONLNdˆ¬NŒZ(ÀN//°dONLNd˚¬òŒ‚)J7you should call ARATickleMe with a state indicator, and°dONLNd4ÕNŸZ(÷N//°dONLNd9ÕòŸö)J+allow your DoMyTickle routine to handle it.°dONLNdf„NÔx(ÏNreturn;°dONLNdnÓ6˙<(˜6}
  2080.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú647ˇ Ädˇ ˇˇˇˇd
  2081. d,     Helvetica
  2082.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0, Palatino
  2083. °dONLNdN6^Í(Z6Appendix C:  Miscellaneous ^4^/
  2084. °dONLNdiHwƒ+Runtime Environment vFv/
  2086. }fi°dONLNd/áZì    +\ARA builds an A5 world for a code resource, so the module can have its own global data.  ARAΩ›°dONLNdåôZ•    *^sets the A5 world automatically, prior to calling any routines (entry, completion) in the code°dONLNdδZ∑Ç*    resource.cÓ°dONLNdı«Z”    *\The module inherits stacks from other executing tasks, and should refrain from recursion and°dONLNdRŸZÂ∂*large stack variables.fû°dONLNdiıZ    *bThe resource file from which the code resources are loaded will be on the top of the resource file °dONLNdÃZ    *Zstack, when ARA executes code resources.  The security module's resource file is opened as°dONLNd'Z%m*readX°dONLNd+n%î)A-only, and you should not attempt to modify or add any resources.°dONLNdm5ZAñ(>ZHYou must initialize any Toolbox manager's you are using (e.g. InitGraf).
  2087. °dONLNd∂GHU(QH#Building  an Add-on Security Module TFT/
  2089. e—°dONLNd⁄eZq    +[You need MPW 3.2 or later and MPW C to build a security module.  The ARA Security Interface°dONLNd6wZÉb*?disk contains the files you need to build a security interface.’¸°dONLNdvìZü    *_The EmptyShell is a good starting point for putting together a code resource.  You can also use=⁄°dONLNd÷•Z±    *`the sample module as the starting point for your module.  This code can be used in your security°dONLNd7∑Z√Ä*Bmodules, but you must keep Apple's copyrights in the source files.Ø…°dONLNdz”Zfl    *`After you have designed your security module (e.g. line-level vs. protocol-level and its workingΩ°dONLNd€ÂZÒ    *`behavior), take the "SecurityShell.c" and code the routines that handle the actions.  The Sample°dONLNd<˜Z€*RModule shows how a protocol-level module that provides a second password is coded.°dONLNdèZu*@You must also define the proper 'sinf' resource for your module.úπ°dONLNd–/Z;    *^After you have compiled the module you must link it with "SecurityInterface.o".  You must alsoM°dONLNd/AZM    *`link in "Runtime.o" (included with MPW).  SecurityInterface.o must be the first file in the link°dONLNdêSZ_Ò*Lcommand.  The link command should also have "-m SECURITYINTERFACEENTRYPROC".°dONLNd›oZ{›*SFor an example of how a security module is build Review the enclosed Sample Module.
  2090.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú648ˇjdˇ ˇˇˇˇd
  2091. d,     Helvetica
  2092.     .ˇ+$,ARA Add-on Security Interface(, Version 1.0
  2093. °dONLNd<HJÊ(FHARA Security Interface Disk IFI/, Palatino
  2095. y°dONLNdZZf    +`The enclosed developer disk contains the interface files and sample modules you can use to build°dONLNd}lZx°*Kan ARA security module.  This sections describes the contents of this disk.ˇˇ˛x°dONLNd…àZî    *fThe "Empty Shell" folder contains a file you can use to build a code resource file.  It contains place°dONLNd0öZ¶,*/holder routines for processing the ARA actions.{Æ°dONLNd`∂Z¬    *[The "Sample Protocol Module" folder contains the complete source for a security module that‚Y°dONLNdº»Z‘    *[provides a second password.  Using this module, you can assign each user a second password.y °dONLNd⁄ZÊß*This is a protocolö~°dONLNd+⁄ßÊ)MO-level module.  You can use this code as a starting point for building your own°dONLNd{ÏZ¯~(ıZmodule.…Ó°dONLNdÉZ    *X"Security Interfaces" folder contains the various header files for interfacing with ARA.∏ˆ°dONLNd›Z&    *a"SecurityInterface.h", and "SecurityPublic.h" contain all the declarations that your module needst°dONLNd?,Z8    *`for accessing ARA Service Routines.  "SecurityResInfo.h" contains the flags that are used in the°dONLNd†>ZJ–*X'sinf' resource.  "SecurityTypes.r" has the resource declarations for a security module.'°dONLNd˘ZZf    *d"SecurityLibraries" contains "SecurityInterface.o" that must be linked as the first file for each of°dONLNd^lZxµ*your code resources.
  2096.     (Ú$*Copyright © 1992, 1993 Apple Computer Inc.(Ú649ˇ